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Preface 



This manual describes the RL5I linker and locator and the LIB51 librarian for 
program modules produced by MCS-51 language translators such as ASM51 and 
PL/M-51. 

The RL5I and the LIB51 program operate on an Intel development system with an 
8080 or 8085 processor. The configuration must include 64K of RAM, a console, and 
at least one diskette or hard disk drive. 

NOTE 

In this manual, the term MCS-51 refers to all members of the MCS-51 family 
of microcomputers and to the software development tools for the MCS-51 
family. 



Reader's Guide 

The manual is organized into six chapters and five appendixes: 

Chapter 1 discusses the advantages of modular programming and summarizes the 
process of modular programming with the MCS-51 development tools. 

Chapter 2 reviews the mechanics of linkage and location for the RL51 program. 

Chapter 3 gives the details on invoking the linker/locator. 

Chapter 4 discusses the files and displays produced by the RL51 program, with 
examples. 

Chapter 5 contains three examples of programs, with the link and locate steps for 
each program. 

Chapter 6 describes the LIBS 1 , the MCS-51 library manager and its usage. 

Appendix A presents the syntax of the RL51 commands with brief definitions of the 
controls. 

Appendix B lists the error messages and warnings displayed by RL51, with suggestions 
for corrective action. 

Appendix C lists a summary of LIB51 commands. 

Appendix D lists the error messages generated by LIB51, with suggestions for 
corrective action. 

Appendix E contains hexadecimal-decimal conversion tables as a convenient reference. 



Related Publications 

The following list provides the manual title and order number for all Intel software 
development tools that jun on DOS systems. Note that some manuals have two 
formats and two order numbers. One version of the manual is provided in a binder. 
This version is not sold separately; it can only be purchased when purchasing a 
software product. The second version, which has a soft cover, is sold separately. Use 
the soft cover number when ordering a manual separately. 
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Notational Conventions 



UPPERCASE Characters shown in uppercase must be entered in the order 

shown. Enter the command words as shown, or use a system- 
defined abbreviation. You may enter the characters in upper- 
case or lowercase. 



italic 



directory-name 

filename 
system-id 

Vx.y 

I I 
{ > 

{ }... 



Italic indicates a meta symbol that may be replaced with an 
item that fulfills the rules for that symbol. The actual symbol 
may be any of the following: 

Is that portion of a pathname that acts as a file locator by 
identifying the device and/or directory containing the 

filename. 

Is a valid name for the part of a pathname that names a file. 

Is a generic label placed on sample listings where an oper- 
ating system-dependent name would actually be printed. 

Is a generic label placed on sample listings where the version 
number of the product that produced the listing would 
actually be printed. 

Brackets indicate optional arguments or parameters. 

One and only one of the enclosed entries must be selected 
unless the field is also surrounded by brackets, in which case 
it is optional. 

At least one of the enclosed items must be selected unless the 
field is also surrounded by brackets, in which case it is 
optional. The items may be used in any order unless other- 
wise noted. 



I The vertical bar separates options within brackets [ ] or 

braces { r . 

Ellipses indicate that the preceding argument or parameter 
may be repeated. 

|, ...| The preceding item may be repeated, but each repetition must 

be separated by a comma. 
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punctuation Punctuation other than ellipses, braces, and brackets must be 

entered as shown. For example, the punctuation shown in the 
following command must be entered: 

SUBMIT PLM86(PRGGA,SRC : ,»9 SEPT 81') 



input lines 



In interactive examples, user input lines are printed in white 
on black to differentiate them from system output. 



Indicates a carriage return. 
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Introduction 



The Advantages of Modular Programming 

Many programs are too long or complex to write as a single unit. Programming 
becomes much simpler when the code is divided into small functional units. Modular 
programs are usually easier to code, debug, and change than monolithic programs. 

The modular approach to programming is similar to the design of hardware that 
contains numerous circuits. The device or program is logically divided into "black 
boxes" with specific inputs and outputs. Once the interfaces between the units have 
been defined, detailed design of each unit can proceed separately. 

Efficient Program Development 

Programs can be developed more quickly with the modular approach because small 
subprograms are easier to understand, design, and test than large programs. With the 
module inputs and outputs defined, the programmer can supply the needed input and 
verify the correctness of the module by examining the output. The separate modules 
are then linked and located into one program module. Finally, the completed program 
is tested. 



Multiple Use of Subprograms 

Code written for one program is often useful in others. Modular programming allows 
these sections to be saved for future use. Because the code is relocatable, saved modules 
can be linked to any program that fulfills their input and output requirements. With 
monolithic programming, such sections of code are buried inside the program and are 
not so available for use by other programs. 

If you put your frequently-used subprograms into a library, RL51 will take care to 
load only those you need. Thus, you can save RAM and ROM without having to 
keep track of what is needed and what is not. 

Ease of Debugging and Modifying 

Modular programs are generally easier to debug than monolithic programs. Because 
the modular interfaces are well-defined, problems can be isolated to specific modules. 
Once the faulty module has been identified, fixing the problem is considerably simpler. 
When a program must be modified, modular programming simplifies the job. You 
can link new or modified modules to the existing program with confidence that the 
rest of the program will not be changed. 



MCS®-51 Modular Program Development Process 

This section is a brief review of the program development process using an MCS-51 
language translator (e.g., the relocatable MCS-5I assembler or PL/M-5I compiler), 
linker/locator, code converter programs, PROM programmer, and ICE™-5 1 in-circuit 
emulator. The process is shown in figure I- 1. 
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121737-1 

Figure MCS®-51 Program Development Process 



Segments, Modules, Libraries, and Programs 

In the initial design stages, the tasks to be performed by the program are defined and 
then partitioned into subprograms. Here are brief introductions to the kinds or 
subprograms used with the MCS-51 assembler and linker/locator, 

A segment is a unit of code or data memory. A segment may be relocatable or 
absolute. A relocatable segment in a module can be a complete segment or can be a 
"partial" segment to be combined with other partial segments from other modules. 
A relocatable segment has a name, type, and other attributes that allow the linker to 
combine it with other partial segments, if required, and to correctly locate the segment. 
An absolute segment has no name and cannot be combined with other segments. See 
Chapter 2 for more detail on partial segments. 

A module contains one or more segments or partial segments. A module has a name 
assigned by the user. The module definitions determine the scope of local symbols. 
An object file contains one or more modules. You can add modules to a file by trans- 
fering the new modules from their individual files to another file. 

A library is a file that contains one or more modules. A library file is internally 
marked as a library, so RL5I can easily identify it as such. RL51 selects, out of the 
modules in the library, only those previously referenced. Libraries are created using 
the LIBS I utility, whichjs described in detail in Chapter 6. 

A program consists of a single absolute module, merging all absolute and relocatable 
segments from all input modules. The name of the output module produced by RL51 
can be defined by the user or allowed to default to the name of the first input module. 
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Entering and Editing Source Modules 

After the design is completed, use the text editor on your system to code the modules 
into source files. The source modules are coded in assembly language or a high-level 
language such as PL/M-51. The editor may also be used to make corrections in the 
source code. 



Assembly and Compilation 

The assembler (ASM51) and compiler (PL/M-51) translate the source code into 
relocatable object code, producing an object file. The ASM 5 1 object file is relocata- 
ble when at least one input segment is relocatable; otherwise the object file is an 
absolute file. The PL/M-5I object file is always relocatable. The assembler and 
compiler also produce a listing file showing the results of the translation. When the 
ASM5I or PL/M-5I invocation contains the DEBUG control, the object file also 
receives the symbol table and other debug information for use in symbolic debugging 
of the program. 



Relocation and Linkage 

After translation of all modules of the program, the linker/locator, RL5I, processes 
the object module files. The RL5I program combines relocatable partial segments 
with the same name, then assigns absolute memory locations to all the relocatable 
segments. RL5I also resolves all references between modules, using the library files 
when they are necessary for this resolution. RL51 outputs an absolute object module 
file that contains the completed program, and a summary listing file showing the 
results of the link/locate process, including a memory map, symbol table, and, 
optionally, an inter-module cross-reference (IXREF) listing. 



ROM and PROM Versions 

The absolute object module produced by RL5I can be loaded into members of the 
MCS-5I family of microcomputers, for ROM versions of the microcomputer, the 
program is masked into ROM during the manufacturing process. For PROM versions 
and versions with no on-chip CODE memory, a PROM programmer is used to load 
the absolute module into program memory accessible to the microcomputer for 
execution. Refer lo the MCS-51 Family of Singh' Chip Microcomputers User's 
Manual for details on the versions of microcomputers available. 



ICE™-51 In-Circuit Emulator 

The ICE-51 in-circuit emulator is used Tor software and hardware debugging and 
integration into the final product. The absolute object modules produced by RL5I 
can be loaded into the emulator's memory for execution. Refer lo the ICE-5 1 manual 
listed in the preface for details. 



Keeping Track of Files 

It is convenient to use the extensions of filenames to indicate the stage in the process 
represented by the contents of each rile. Thus, source code Hies can use extensions 
like .SRC, .A5l, or .P51 (indicating that the code is for input to ASM5I or 
PL/M-51). Object code files receive the extension .OBJ by default or the user can 
specify another extension. Executable files generally have no extension. Listing files 



can use .LST, the default extension given by the translator. RL5I uses ,M5l for the 
default listing file extension (in order not to destroy the ASM51 listing file with the 
.LST extension). 

Library files customarily have the extension .LIB. 

Use caution with the extension .TMP, as many utilities (including RL5I and LIB51) 
create temporary files with this extension. These utilities will delete your file if it has 
the same name and extension as the temporary files they create. 



The Mechanics of Linkage and 
Location with RL51 



This chapter describes the operation of the RL51 program. Most of the process is 
transparent to the user; however, an understanding of the operation at the level 
presented here will help you to use the linking and locating controls in the RL51 
invocation, More specific details on the allocating process appear in Chapter 3. 



Major Functions 

The RL51 program performs the following major functions: 

1. Selects modules (including library processing) 

2. Combines relocatable partial segments of the same name into a single segment 

3. Allocates memory for the combined segments resulting from the previous step, 
. and for all other complete relocatable segments from the input modules 

4. Overlays data segments 

5. Resolves external symbol references between the input modules 

6. Binds relocatable addresses to absolute addresses 

7. Produces an absolute object file 

8. Produces a listing file consisting of a link summary, a symbol table, and an IXR EF 
report 

9. Detects and lists errors found in the input modules or in the RL5I command 
invocation 

Functions I, 2, 3, 5, and 6 are described in the remainder of this chapter. Functions 
7, 8, and 9 are discussed in Chapter 4; the RL5I command invocation and overlaying 
of data segments are described in Chapter 3. 



Selecting Modules 

Input files are processed in the order they are specified in the invocation command. 

The processing of an input file varies according to the content — that is, whether it is 
a library or non-library file. A non-library file may contain a concatenation of zero 
or more object modules. A library file contains zero or more object modules together 
with control information. A module in a non-library file is processed if it was explic- 
itly listed in the module list, or if the module list was not specified at all (in other 
words, as if all modules were listed implicitly). 

The processing of a library file is more complicated. If a module list was specified 
for the library file, then it is processed in the same manner as a non-library file. If a 
module list was not specified, then the library file is processed only if the previously 
processed modules contained at least one unresolved external. The library is scanned 
for modules containing public symbols that match as yet unresolved externals. Each 
such module is processed as if it were explicitly specified. The selection process 
continues until the mod.ules in the library cannot satisfy any unresolved externals 
(including any externals encountered while processing modules from the library). 

RL5t will report an error if the same module name is encountered more than once 
during the link process. 
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Take TRIGON.LIB as an (utterly fictitious) example. Assume it contains procedures 
called SINE, COSINE, TANGENT, ARCSINE, ARCCOS, ARCTAN, HYPER- 
BOLIC_SINE, and HYPERBOLIC__COSINE. 

When RL51 starts processing TRIGON.LIB, it has already made a first pass over 
all files that appear before it in the invocation line. If one of these contains a refer- 
ence to the external SINE, and there is no public by that name, RL5I will assume 
that the procedure SINE from TRIGON.LIB is to be loaded. Otherwise, it will leave 
SINE alone for the moment. 

If, while loading from TRIGON.LIB, RL5I encounters new externals that a module 
in the library can resolve, it will scan the library once more. Thus, there is no logical 
order among modules in a library; they are all equal. If TANGENT calls SINE and 
COSINE, and they are in the same library, in any order whatsoever, a reference to 
TANGENT will cause all three to be loaded. 



Partial Segments 

A segment is a unit of code memory or data memory. The portion of a segment 
defined in one moduli: is called a partial segment. A partial segment has the following 
attributes (defined in the source module): 

• Name. A relocatable segment has a name by which it is linked with other portions 
of the same segment from other modules. Absolute segments do not have names. 

• Type. The type identifies the address space to which a segment belongs: CODE, 
XDATA. DATA, I DATA, or BIT. 

• Repeatability. For relocatable segments only, this attribute describes any special 
constraints on relocation (PAGE, INPAGE, BLOCK, BITADDRESSABLE, or 
UNIT). 

• Size. The size of the segment in bytes or bits, depending on the type. 

• Base Address. The lowest address in the partial segment. For absolute segments, 
the base address is assigned at assembly time; for relocatable segments, it is 
assigned at location time. 

Absolute segments arc complete segments; they are taken as is into the output module. 
Relocatable segments are either defined by ASM 5 1 users (using the SEGMENT 
directive in the source module) or automatically generated by the PL/M-5I compiler. 

Refer to the MCS-51 Macro Assembler User's Guide for details on the assembler 
directives. 



Combining Relocatable Segments 

After processing the invocation command, RL5I performs a first pass over the input 
modules identified in the command. Pass I generates a segment table, a publics table, 
and an unresolved externals table. The segment table is discussed in this section; the 
other two tables are discussed later in this chapter. 

The segment table contains the name, length, type, and relocation attribute of all 
combined segments from all modules. Combined segments are produced from the 
partial segments in the input modules according to the following rules: 

• RL51 combines all"partial segments with the same name into one relocatable 
segment. For example, if three input modules each have a partial relocatable 
segment named STACK, the segment table will have one segment named STACK 
that combines the length of the three partial segments. 
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• All the partial segments to be combined must be of the same type (CODE, DATA, 
IDATA, XDATA, or BIT). If any partial segments have trie same names but 
different types, an error occurs. 

• The length of the combined segment must not exceed the physical size of the 
memory type. Details on maximum size appear later in this chapter. 

• The relocation attributes of all the partial segments to be combined must either 
be the same or UNlT-aligned combined with one other attribute. The combined 
segment receives the relocation attribute shared by the input partial segments, 
or, if the segments have attribute UNIT-aligned combined with one other attrib- 
ute, the combined segment receives the more restrictive attribute. 

For example, iT the three partial segments named STACK have relocation attri- 
butes UNIT, PAGE, and UNIT, the combined segment has attribute PAGE 
(i.e., page-aligned). Note that the relocation attribute is applied to the combined 
segment, not to each component segment. To continue the example, since the 
relocation is PAGE, the combined segment will start on a page boundary, but 
the component segments will be packed together without any gaps. 



Allocating Memory for Segments 

After the segment table is complete, RL51 can locate the segments within the memory 
spaces. Table 2-1 shows the address spaces used by MCS-51 processors, and the 
corresponding segment types. 

The allocation process has a definite sequence; the exact order is presented in 
Chapter 3. As an overview, the process follows a general pattern of rules as follows: 

1. Each of the types of memory space is allocated independent of the other spaces. 

2. Within each space, absolute segments are allocated first, then segments specified 
within locating controls in the RL51 command, then other relocatable segments. 

3. Because the on-chip data space represents three overlapping address spaces 
(DATA, IDATA, and BIT), the general pattern in rule 2 is modified. 

a. Absolute BIT, DATA, and IDATA segments, and register banks are allocated 
Hrst. 

b. Segments specified in PRECEDE and BIT controls are allocated next, then 
other relocatable BIT (and BIT-ADDRESSABLE) segments (following 
rule 2). 

c. DATA type segments are allocated next: segments in the DATA control first, 
then other relocatable DATA segments. 

d. IDATA type segments (except 7STACK) are allocated next; segments in the 
IDATA conlrol first, then other relocatable IDATA segments. 

e. Segments specified in the STACK control are allocated, at as low an address 
as possible, provided that it is above all BIT, DATA, and IDATA segments 
allocated under (c) and (d). 

f. Last, the segment 7STACK, if it exists and is IDATA, and is not mentioned 
in an explicit location control, is now allocated, at as low an address as possi- 
ble, provided that it is above all BIT, DATA, and [DATA segments allocated 
under (c) and (d) and (e). 

In most cases, you do not need to use any explicit controls to obtain a satisfactory 
allocation of segmenis. RL51 tries to fit your segments into the designated memory 
spaces as best it can following the rules. As you can see, most of the complexity 
occurs in the on-chip data space. 
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Table 2-1 . Address Spaces and Segment Types 



Memory Space 


Maximum Size 


Addresaa* 


Segment Type 


Code 


64K bytes 


OOOOH - OFFFFH 


CODE 


External data 


64K bytes 


OOOOH - OFFFFH 


XDATA 


On-chip data 
(direct addressing) 


128 bytes 


OOH - 7FH 


DATA 


On-chip data 
(indirect addressing) 


256 bytes 
(see 1) 


OOH - OFFH 


IDATA 


Bit space in 
on-chip data 
memory 


128 bits 
(see 2) 


OOH - 7FH 


BIT 



1 . The amount of indirectly addressable on-chip data memory is machine-dependent within the 
MCS-51 microcomputer family (see the discussion of RAMSIZE control in Chapter 3). 

2. This bit space overlaps byte addresses 20H - 2FH in on-chip data memory. 

Note: Addresses in the special function register memory (direct data addresses 80H - OFFH, bit 
addresses 80H - OFFH) cannot be relocated; they are always absolute. Thus, these addresses 
are not referenced in this table. 



Rule (f) applies to PL/M-51. PL/M-51 produces for the stack an IDATA segment 
called 7STACK, whose size is 1, Although, by applying rule (f), RL5I makes the 
stack as big as possible, it is the user responsibility to ensure that the sire of the stack 
is large enough (the segment map shows where the stack is located). 



No rules for the allocation process can guarantee an optima] solution. If you are short 
of memory and RL51's first try is not satisfactory, you can place the segments in 
memory using the locating controls. Details on the locating controls are given in 
Chapter 3. 



Overlaying Data Segments 

On-chip RAM is a scarce resource on the MCS-51. To economize, the PL/M-51 
compiler overlays data segments in the compiled module. RL-51 completes the work 
by overlaying the data segments across modules. This is accomplished by using the 
OVERLAY control. If RL-51 informed you about ignored segments due to lack of 
on-chip RAM, try this control. The use of OVERLAY is, in general, straightforward. 
However, for complex applications (for example, those with mixed ASM-51 and 
PL/M-51 modules), consult Chapter 3. 



Resolving External References 

An external reference points to a location in another module. The EXTERNAL 
declaration for symhols tells RL5I that the reference is to a location defined in another 
module. In the latter module, the symbol is declared PUBLIC so that external refer- 
ences to that symbol in other modules can be satisfied. 

As it processes the input modules, RL5I builds a table or public symbols and 
unresolved external references. As each public symbol is added to the table, any 
external references to that symbol are deleted. After all segments have been located. 
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the public symbols are bound to absolute addresses. RLSI issues a warning for any 
unresolved externals that remain in the table. 

External symbols and corresponding public symbols must be compatible. That is, both 
must be defined to address the same address space, or at least one must be defined 
as a typeless symbol (NUMBER); and if the symbol represents a PL/M-51 proce- 
dure name, then both must share the same register bank (i.e., must be declared within 
the PL/M-51 source modules with the same USING attribute). 



Binding Relocatable Addresses 

After allocating memory for the combined segments and binding the public symbols, 
RL51 makes a second puss (pass 2) through the input modules to build the listing 
file and fixup (i.e., bind to absolute addresses) any relocatable or external references. 
At this point, RL51 also processes debug records if requested, and performs fixups to 
any relocatable debug symbols that require processing to compute their absolute 
addresses. 
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Introduction 

The RL51 program performs two functions for MCS-51 programs: 

• The link function, combining a number of object modules specified in an input 
list into a single object module in an output file 

• The locate function, assigning absolute addresses to any relocatable addresses in 
the input modules 

This chapter explains how to enter commands, how to continue a long command onto 
more than one input line, how to enter comments in the invocation, and how to use 
abbreviations of the command words. 

The chapter then presents a summary of the format of the RL5I invocation command, 
followed by details on the elements of the command with examples. 



RL51 Command Format Summary 

Here is a summary of the syntax of the RL51 invocation command. Refer to the 
Preface for an explanation of the command format notation. 

The RL51 command has the overall format: 

[ directory \ device 1 R L 5 1 input-list t T output-file J [ control-list] 



where 



directory I device 
input-list 



output-file 



control-list 



is the directory or device where RL51 resides. 

is a list of filenames separated by commas. The files named 
in input-list should contain the relocatable modules to be linked 
and located in the final absolute output module. For each 
file, you can additionally specify which modules are to be 
included. 

is the name of the file that is to receive the output module. If 
you omit this entry, the program will supply a default name 
based on the first filename in the input list. 

selects options for listing, linking, and locating the output. 
The listing controls specify what information is to be sent to 
the listing file, and the page width to be used. The linking 
controls specify the name of the output module, and deter- 
mine what debug information is to be placed in the output 
file. The locating controls allow you to assign absolute 
addresses to relocatable segments, and to specify the order of 
relocatable segments within a given type of memory. The 
configuration control is used to describe the actual configu- 
ration the object is aimed to. The overlay control overlays 
«data segments between modules. 

The next several sections give details and examples of the elements of the RL51 
command. Table 3-1 gives brief definitions of some of the terms used in the controls. 
A list of abbreviations for command words appears at the end of the chapter. 



Table 3-1 . Definitions of Common Terms 



Term 


Definition 


name 


Names can be from 1 to 40 characters in length and must be 
composed of letters A - Z, digits - 9, or special characters (?, @, 
_). The first character must be a letter or a special character. 


module-name 


Same as name. 


segment-name 


Same as name. 


pathname 


A valid filename reference or device reference. See next two items 
for examples. 


filename 


A reference to a disk file. 


device 


A reference to a non-disk device. 
Examples: .LP:, :CO:, :TO: 


value 


A 16-bit unsigned integer. 

Exampfes: 1011B. 304Q, 4096D (or just 4096), 0C30OH 


address 


Same as value. 



Invocation 

The RL51 command is a standard operating system invocation. Terminate the 
command with the RETURN key. Note that the termination carriage return is not 
shown in the command format notation. 

You can continue the invocation line on one or more additional lines by entering the 
ampersand (&) before you enter the line terminator. The next line then automati- 
cally appears with the continuation prompt. Comments can also be entered on the 
invocation line by placing the comments after the ampersand or semicolon (;) because 
the compiler ignores all characters that appear after the ampersand or semicolon but 
before the carriage return/line feed that terminates the line. 

Refer to your DOS user's guide for information on submitting batch file commands. 

Input List 

The input list tells RL51 what files are to be processed. The files must be disk files 
containing relocatable object modules as described in Chapter 2. 

The entry for each file in the list can include the following information: 

• The directory or device. If the directory or device is omitted, the default directory 
or device is assumed. 

• The filename. The filename is the name of the object file including an extension 
if one exists. 

• A list of modules enclosed in parentheses. If a module list is provided, only the 
modules in the list are linked into the output file, and modules not in the list are 
ignored. If no module list is provided, the default for a non-library file is to link 
all modules in the file into the output module. The default for a library file is to 
link only those modules that satisfy previously declared external symbols (see the 
exact process in Chapter 2 under "Selecting Modules"). 

If a module named in the module list is not present in the file, the system issues an 
error message but does not halt the link process. 

Module names (specified explicitly or implicitly) must be unique throughout the entire 
application. 
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Examples 

Following are examples of the RL5I input list — 

1. > R L 5 1 ft:prog.obj TO A:prog.abs 

In this example, the input list has one file (prog.obj in directory A:); RL51 links 
all the modules in this file into the output file (prog.abs). (For clarity, this and 
other examples omit the directory in which RL51 resides; the examples assume 
RL5I resides in the root directory.) 

2. > R L 5 1 a:samp1.ob], o: 5 a m p 2 . o b ] , a;samp3.obJ t 
>> TO b: samp, abi 

In this example, the input list has three files. RL51 links all the modules in each 
of these files into the output file. (Note that the > > in the second line of the 
example is generated by the system in response to the continuation character & 
on the first line of the example.) 

3. > R L S 1 A:PR0G1.0BJ (MODi, M0D3), A: PR0G2.0BJ 4 

> > ( M0D2) TO A : PR0G3 . ABS 

Here, the input list has two input files (PROG I. OBJ and PROG2.0BJ). From 
PROGl.OBJ, only the modules named MODI and MOD3 are to be linked into 
the ouptut file; any other modules in file PROGl.OBJ are ignored by RL51. 
From PROG2.0BJ, only the module named MOD2 is to be linked. 

4. > R L S 1 atplmprg.obj, a:util51.11b, a : 1 o S 1 . 1 1 b , I 

> > p 1 m 5 1 .lib 

The example introduces a typical linking using libraries. Here, plmprg.obj is linked 
with two private libraries and with the mandatory library plm5l.lib (which must 
be used if modules generated by plm51 participate in the linkage). 

5. > R L B 1 asexampl.ob], cotrlg.llb, trig, lib, I 
>> cotrlg.llb 

Interaction between libraries (i.e., libraries that reference each other) may 
sometimes require the same library to be mentioned twice in the input list. 

In the preceding example, cotrig.lib contains the COTANGENT and COSINE 
trigonometric functions, trig. lib contains the SIN and TANGENT functions, and 
exampl.obj references the COTANGENT function. 

Because COTANGENT equals 1 /TANGENT, trig. lib must be specified to 
resolve the reference to the TANGENT function. Also, because TANGENT 
equals SINE/COSINE, cotrig.lib must be respecified to resolve the reference to 
the COSINE function. 



Output File 

The output filename is the name of the disk file that is to receive the absolute object 
module. 

If the output file name is omitted, RL5I creates a filename for the output file by 
removing the extension from the first filename in the input list and using the drive 
and root name only. If this input file contains no extension, a fatal error occurs. For 
example, the command: 

RL5 1 PROG 1 

is illegal since the output filename defaults to PROG I. 

If there is already a file on the target drive with the name of the output file, that file 
is overwritten by the new output file. 
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Examples 

Following are examples of RL5I output file — 

1. > R L 5 1 a:prog.ob] TO c:prog 

This example specifies file prog in directory c: as the output file. 

2. > R L 5 1 C:PR0G.0BJ 

This example uses the default output file generated by RL5I. The effect is the 
same as the first example; the output file becomes c:prog. 

3. > r I 5 1 a:aample1.obJ, a:sample2.obJ TO t 
)> c:\myflle\sampl.abs 

In this example, the output file is in a different directory than the input files, and 
the directory, filename SAMPL, and the extension .ABS are specified. 



Controls 

After the output filename, you can add a list of controls to select options for listing, 
linking, and locating the output. Use blanks (not commas) to separate controls in the 
list. The same control may not appear more than once in the list; if a duplicate control 
is encountered, a fatal error results and the program aborts. The next several sections 
explain the controls and give examples. 



Listing Controls 

The listing file output by RL5I can contain a link summary, a symbol table, an 
IXREF report, and ;i list of error messages. The link summary can contain a memory 
map of the linked segments. 

The listing controls are the PRINT option, the PAGEWIDTH control, the MAP 
option, the SYMBOLS option, the PUBLICS option, the LINES option, and the 
IXREF option. These controls allow you to specify the file or device to receive the 
output listing, to omit the listing file altogether, to omit the map from the link 
summary, or to omit local symbols, public symbols, or line numbers from the symbol 
table. You may also specify if you wish to have the IXREF report generated, and the 
specific page width to be used. 

NOTE 

The information in the listing file is taken from the input object modules. If 
these are generated without the DEBUG option, the SYMBOLS, PUBLICS, 
and LINES information will not be available for listing. 

PRINT/NOPRINT 

The print options control the destination of the list file. 

To direct the list file to a disk file, the print control format is 

PRINT ( [ directory/device] filename I .ext] ) 

Example 

> R L 5 1 a : ) amp I c 1 . ob j I 
>) print (ajsample.lst) 
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To direct the list file lo a device other than a disk file, the print control format is 

PRINT ( : device : ) 

where 

device is a device code. Common devices are CO (console), LP (line 

printer), TO (terminal other than console), and VO (video 
terminal screen). 

If you omit the print control, or if you enter the command word PRINT without a 
filename or device name, RL5I creates a disk file for the listing. The name of the 
default listing file has the same root as the output filename and has an extension of 
M5l; the drive number is also the one used in the output filename. 



Example 

> R L 5 1 A:PR0G.DBJ, A:PR001.0BJ TO B-.PR0G2.ABS 

The output listing filename may not be the same as the output filename or any of the 
filenames in the input list. If the listing file duplicates an input or output filename, a 
fatal error results. If the listing filename already exists on the target directory, the 
old file with that name is overwritten by the new listing file. 

The NOPRINT option specifies that no output listing Hie is to be produced. 
NOPRINT overrides the MAP, SYMBOLS, PUBLICS, LINES and IXREF 
controls. 



PAGEWIDTH 

The PAGEWIDTH control specifies the maximum number of columns per line in 
the print output file. The control takes the form 

PflGEWl D T H ( width ) 

where 

width is an unsigned number which specifies the maximum page 

width to be used. 

The allowable range for width is 72 to 1 32. The default PAGEWIDTH is 78. 



Listing Switches 

The MAP, SYMBOLS, PUBLICS, LINES and IXREF controls select what portions 
of the listing files are to be generated. The default of any switch (with the exception 
of IXREF) is the positive form (MAP, SYMBOLS, PUBLICS, and LINES). 
Table 3-2 summarizes the listing switches. 



IXREF /NOIXREF 

This control specifies whether or not to produce the inter-module cross reference 
report. If IXREF is specified, the report is appended to the print file. 

A selection list may be added vo the positive form (only) of the IXREF control. A 
selection list causes RL51 to output or suppress output of various selected entries to 
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Table 3-2. Listing Switches 



Switch 


Effect 


MAP 


Output memory map to link summary 


NOMAP 


Suppress memory map 


SYMBOLS 


Output local symbols to symbol table 


NOSYMBOLS 


Suppress local symbols 


PUBLICS 


Output public symbols to symbol table 


NOPUBLICS 


Suppress public symbols 


LINES 


Output line numbers to symbol table (high-level language transla- 
tors only) 


NOLINES 


Suppress line numbers 


IXREF 


Append intermodule cross-reference report to print tile 


NOIXREF 


Suppress the intermodule cross-reference report 



the IXREF report. An entry consists of a symbol and a module where this symbol is 
referenced (either as public or as external). The general form of the IXREF control 

is 

IXREF t ( selection-item [,...])] 
where 

selection-item is either (NO)GENERATED or (NO)LIBRARIES. ir 
IXREF is specified and any or the selection items are omitted, 
the missing selection item assumes its positive form. A selec- 
tion item may appear at most once. 

The selection-items are best explained by describing the effect of their negative form. 

The NOGENERATED control causes RL51 to surpress output of entries whose 
symbol name begins with a question mark (?); such symbols are usually PL/M-51 
generated symbols. The GENERATED form of the control causes RL51 to output 
such entries also. 

The NOLIBR ARIES control causes RL51 to surpress output of entries whose module 
resides within a library. The LIBRARIES form of the control causes RL5t to include 
all libraries in the IXREF report. 

The selection list is used to control the number of entries collected for the IXREF 
report. This is needed when an excessive number of IXREF entries make it impossi- 
ble for RL5I to generate the IXREF report. 

Examples 

1. > R L 5 1 a : p r o g . o b J nosymbols nopubltcs nolLnea 

Because the default for any listing switch (except ixref) is the positive form, the 
main use of the switches is to suppress unwanted information. The invocation 
given in this example will suppress the entire symbol table. 

2. > r 1 5 1 a : prog.ob] print (a:prog.m51) nomap no jb I 
> > noli 

In this example, only the public symbols will be printed (no map or other symbols 
or lines). Note the use of abbreviations (nosb for nosymbols and noli for nolines) 
to save keystrokes. A complete list of abbreviated forms appears at the end of 
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Chapter 3. Note that the blank separating print from its parameters is optional; 
you could also use print(a:prog.m51 ). 

3. > R L 5 1 a : prog , ob J , aiprocs.ob], a : p 1 m 5 1 . 1 1 b t 
>> ixref(nogn) 

This example suppresses generated symbols from the ixref report. Using the nogn 
(nogenerated) selection item prevents PL/M-51 run-time library procedures from 
being written to the ixref report. 



Linking Controls 

The linking controls allow you to name the resultant output module and to specify 
which debug information is to be copied to the output module. 

NOTE 

In order to obtain the debug information (SYMBOLS, PUBLICS, or 
LINES), the DEBUG control must be included in the invocation line for the 
translator used to produce the input modules. 

NAME 

The NAME control allows you to name the output module. The format is 
NAME ( module-name ) 

If the NAME control is not used, the output module-name defaults to the name of 
the first input module processed. 

Example 

> R L 5 1 a: sampll.obj, a:sampl2.ob] TO ojsample.aba I 
>> name( S A M P L E_P R G R A ft ) 

In this example, the name SAMPLE_PROGRAM is assigned to the output module. 
Note that the blank between NAME and its parameter is optional and can be omitted. 



Linking Switches 

The DEBUGSYMBOLS, DEBUGPUBLICS, and DEBUGLINES controls select 
what kinds of debug information are to be included in the output file. The default of 
any switch is always the positive form (DEBUGSYMBOLS, DEBUGPUBLICS, and 
DEBUGLINES). Table 3-3 summarizes the linking switches. 

Examples 

1. > R L 5 1 a : p r o g 1 . o b J nodebugsymbols nodebugllnes 

Because the linking switches default to the positive form, you will usually use the 
negative forms to suppress unwanted debug information in the output file. In this 
example, the output-file contains only the information for the public symbols. 

2. > R L 5 1 a : p r o g 1 . o b J n o d p nodi 

In this example, only the local symbols are output to the absolute file. Note the 
use of abbreviations (nodp for nodebugpublics and nodi for nodebuglines). 
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Table 3-3 . Linking Switches 



Switch 


Effect 


DEBUGSYMBOLS 

NODEBUGSYMBOLS 

DEBUGPUBLICS 

NODEBUGPUBLICS 

DEBUGLINES 

NOOEBUGLINES 


Copies local symbol information to output file 
Suppresses local symbols 
Copies public symbol information to output file 
Suppresses public symbols 

Copies line number information (high-level language translators 
only) to output file 

Suppresses line numbers 



Locating Controls 

The locating controls allow you to assign absolute addresses to relocatable segments, 
to specify the ordering of relocatable segments of a given type in memory, and to 
force allocation of segments into a specific range of addresses. 

Allocation Sequence 

The system allocates memory in accordance with segment attributes and locating 
controls, using a fixed order of precedence. The precedence of the allocating opera- 
tions {grouped by type of memory space) is as follows: 

Internal Data Space: 

• Absolute BIT, DATA, and IDATA segments, and register banks 

• Segments specified in a PRECEDE control in the RL5I command 

• Segments specified in a BIT control in the RL5I command 

• DATA type segments with relocation equal to BIT-ADDRESSABLE 

• Other relocatable bit segments 

• Segments specified in a DATA control in the RL51 command 

• DATA type segments with relocation equal to UNlT-aligned 

• Segments specified in an IDATA control in the RL5I command 

• Other relocatable IDATA segments, except 7STACK 

• Segments specified in a STACK control in the RL51 command 

• 7STACK, if it is IDATA and has not been specified in any other locate control 
External Data Space: 

• Absolute external data segments 

• Segments specified in an XDATA control in the RL51 command 

• Other relocatable external data segments 

Code Space: 

• Absolute code segments 

• Segments specified in a CODE control in the RL51 command 

• Other relocatable code segments 

NOTE 

In most cases, the allocation algorithm will produce a workable solution 
without requiring the user to enter any locating controls in the RL51 
command. These controls are intended for the experienced user, in cases where 
running RL51 without them does not give a good enough result. 
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Format Summary 

The locating controls have the format 
control c segment I , . , . ) ) 
where 

segment : • segment-name I ( base-address ) ] 

The segments specified in the locating controls are allocated in the order they appear; 
the first segment is assigned the lowest possible address, and succeeding segments 
receive higher and higher addresses. 

The user has the option of specifying the base address of any or all segments. Segments 
with specified base addresses must appear in the list in ascending numerical order. 
Segments named in a locating control with a specific base address are allocated at 
that address irrespective of segment overlap or segment type contradiction, as long as 
ascending order is maintained. Base addresses are byte addresses except for the BIT 
locating control, where addresses are bit addresses in the bit spaceO to 127). 

Table of Locating Controls 

Table 3-4 lists the locating controls in order of precedence. The first column gives 
the name of the control. The second column describes the address space affected by 
the control. The third column gives the address range for segments within each control. 
The last column shows what types of segments are allowed for each control; for each 
valid type, the column also shows the allowable relocation attributes. (Refer to the 
MCS-51 Macro Assembler User's Guide and PL/M-51 User's Guide for details on 
segment types and relocation attributes.) 

Notes On Locating Controls 

The following notes refer to table 3-4. 

1. Bit addresses for non-BIT segments in the BIT control must be on byte bounda- 
ries; that is, they must be divisible by eight. (BIT-type segments can be aligned 
on bit boundaries.) 



Table 3-4. Locating Controls 



Control 


Address Space 


Address Range 
(Hex) 


Segment Type* 
(and Attributes) 


PRECEDE 


Register banks and bit- 
addressable space in 
on-chip data RAM 


00H-2FH 


DATA (UNIT-aligned); 
IDATA 


BIT 


Bit-addressable space 
in on-chip data RAM 


00H - 7FH 
(see note 1) 


BIT; DATA; IDATA 


DATA 


Directly-addressable 
on-chip data RAM 


00H - 7FH 


DATA (UNIT-aligned); 
IDATA 


IDATA 


Indirectly-addressable 
on-chip data RAM 


00H - OFFH 
(see note 2) 


IDATA 


STACK 


Same as IDATA (see 
note 3) 


Same as IDATA 


Same as IDATA 


XDATA 


External data RAM 


- OFFFFH 


XDATA 


CODE 


Code memory 


- OFFFFH 


CODE 
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2. The range of addresses for the I DATA control is dependent on the target machine. 
See the RAMS1ZE control later in this chapter. 

3. The STACK control specifies which segments are to be allocated uppermost in 
the I DATA space. The memory accessed starts after the highest on-chip RAM 
address occupied by any previously allocated segment and continues to the top 

of the 1DATA space. '\ /' 

NOTE 

This control has no other effect on any segments. 

The I DATA 7STACK segment, if it exists, is placed higher than segments 
that were mentioned in the STACK control. 

The STACK control provides a convenient way to handle the stack (usually for 
ASM51-based application, where '.'STACK is not used). 

First, assign the stack pointer (SP) to a relocatable segment; consider the following 
ASM51 example: 

STACK_AREA SEGMENT IDATA ; SEGMENT directive In source. 

DS 1 H ; Reserve 16 bytes for stack. 

Other CODE Instruction*. 

MOV SP, *STACK_AREA- 1 ; Initialize SP, 

Then, at relocation time, specify the segment named STACK_AREA in a STACK 
locating control: 

R L 5 1 ... STACK (STACK „A R E A ) V J 

where 

ellipsis (...) represents the rest of the invocation line exclusive of the 

STACK control. 

NOTE 

If the application contains modules produced by PL/M-51, the 7STACK 
should be used as the slack segment. 



Examples 

1. > R L 5 1 A : PROG 1 . OBJ , A:PR0G2.0BJ TO A:PROG.ABS i 
>> PRECEDE (MESSAGE1) XDATfl (ARRAY1 (256), t 
>> ARRAY2 (512)) 

In this example, the DATA (or IDATA) segment names MESSAGEl will be 
allocated space in on-chip RAM in the lowest available location, overlapping the 
BIT space if necessary. The XDATA control specifics that the two arrays are to 
be located at specific addresses (e.g., for debugging), 

2. >RLS1 A:TEST.OBJ STACK (STACK _A R E A ) 

Here, the STACK control allocates the uppermost portion of IDATA space for 
the segment named STACK_AREA. 

3. > R L S 1 APROG.OBJ, BPROG.OBJ, PL M 5 1. LIB 1 
>> CODE (MOD-1 C 4 H J , M0D2, M0D3) 

Here, the CODE control allocates space in code memory for segments MODI, 
MOD2, and M0D3. MODI is aligned at location 4000H. MOD2 and MOD3 
are assigned contiguous addresses after MODI. 
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Configuration Controls 

The configuration controls are used to describe the actual configurations that objects 
are aimed to. 

This group contains the RAMSIZE control. 
RAMSIZE 

The RAMSIZE control format 

RAMS I ZZ lvalue) 

where 

value is a number in the range 1 28 to 255. 

RAMSIZE specifies the maximum amount of on-chip RAM that may be allocated 
for the user program. The default value for RAMSIZE is 1 28 (as is the case for the 
805 1). If the object is aimed at more than one configuration or the MCS-51 family, 
specify the MINIMUM of all on-chip RAM sizes among all machines you want to 
link. 

The sole use of this control is to enable RL5 1 to check on-chip memory size constraints 
at RL-time and thus avoid confusion at ICE-time. 



OVERLAY/ NOOVERLAY Controls 

The linker allows overlaying of on-chip RAM segments among modules, under the 
specification of the OVERLAY control. Two segments can be overlaid if all the 
following conditions exist: 

• The segments have the same type (DATA, I DATA, BIT, or 
BITADDRESSABLE). 

• The segments use the same register bank (determined by the USING attribute 
or the REGISTER BANK control). 

• The segments are marked as overlayable. Currently, this is done only by the 
PL/M-5I compiler. ASM5I (V2.l and lower) lacks this feature. Therefore, 
assembler segments are considered non-overlayable. 

• The segments belong to disjoint modules. That is, no procedure in one module 
can directly or indirectly call a procedure from the other. 

The default is NOOVERLAY. No overlaying of on-chip RAM segments is done by 
the linker. 

The general form of the OVERLAY control is as follows: 

OVERLAY t ( overlay-unit [ ,...]) ] 

where 

overlay-unit is ov-module-name calls ov-module-name. 

ov-module-name is a legal RL5I module name or *, which stands for all the 
module names. 

calls is > or 1 . 
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OVERLAY 

If the OVERLAY control appears in the invocation line without arguments, the linker 
assumes that no intra-module calls exist except for those deducible from the PUBLIC- 
EXTERNAL declarations, and that overlaying of all overlayable segments is safe. 



NOOVERLAY 

The linker does not overlay data segments. 



OVERLAY (A > B) or (A ] B) 

If the OVERLAY control appears in the invocation line with arguments, it indicates 
that there are invisible calls between modules. In the OVERLAY control syntax, 
either the greater than sign ( > ), or the right square bracket ( 1 ) may be used in the 
calls relationship. The greater than sign will be used in the text. The notation A > B 
means that module A calls module B. In this case, the linker overlays all overlayable 
segments, except that segments from A are not overlaid by segments from B. Note 
that the added connection can prevent other segments from overlaying. For example, 
if the segment A was overlaid with the segment D, and B calls D (visibly by PUBLIC- 
EXTERNAL declarations), then the effect of A > B is that A and D will not be 
overlaid, since A can call D through B. 



OVERLAY (A > *, * > B) or (A ] 7 ] B) 

A module can be declared as non-overtayable in two ways. The argument A > * 
indicates that the module A calls all other modules. On the other hand, * > A means 
every module calls A. In either case, no segments from A will be overlaid. The effect 
of each form depends on the nature of A. For example, if the • > A form is used and 
A visibly calls all other modules, then every module can call (through A) each other 
module. In this case, the linker will not perform any overlays. 

The overlaying of data segments in on-chip RAM has the following restrictions: 

♦ The OVERLAY control cannot be invoked with the IXREF selection items 
NOGENERATED or NOLIBRARIES. RL51 generates an error if either one 
is specified. 

• Combined segments and segments appearing in locating controls are not overlaid 
by the linker. 

Following is an example in which two disjoint modules share the same on-chip RAM 
area: 

modi: DO; 

THREE _ BEARS: PROCEDURE PUBLIC; 

DECLARE L 1 TTLE_BEARS_BED BYTE; 

IF BOOLEAN < L I T T L E _ B E A R 5_B E D ) THEN 

CALL MSG( .(' SOMEONE '* S BEEN IN MY BED!'),0); 

L I TTLE_.BEARS_BED • ; 
END THREE _B EARS', 

END mod 1 ; 
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m o d 2 : DO ; 



GOL 


DILOCKS: PRO 


C E DU 


RE PUBLIC 




DECLARE SP 


A R E_ 


BED BYTE ; 




SPAR E_B E D 


■ I ; 




END 


GOLDILOCKS; 







END mod2 ; 

I ti_! lory : DO; 

THREE_BEARS: PROCEDURE EXTERNAL; END; 
GOLDILOCKS: PROCEDURE EXTERNAL; END; 

CALL T H R E E_B EARS; 
CALL GOLDI LOCKS ; 
CALL T H R E E_B EARS; 

END ita I n_! lory ; 

In this example, the linker reserves the right to use the LITTLE_BEARS„BED as a 
SPARE_BED because the two procedures are never active simultaneously. 

To perform overlaying, the linker must determine which procedures are active simul- 
taneously. To do this, the linker assumes that all CALLs can be executed. For example, 
if procedure A calls procedure B, and B calls procedures C and D, then the linker 
can overlay RAM variables from C only with the RAM variables of D. 

The linker, however, looks only at the PUBLIC-EXTERNAL declarations. It assumes 
that any reference to an EXTERNAL procedure will be executed, but ignores the 
possibility of hidden calls. The arguments to the OVERLAY control are therefore 
needed to specify those interconnections between modules that cannot otherwise be 
detected by the linker. 

Such situations arise if the interconnection is done by a computed call to an external 
procedure whose address is not determined by a simple PUBLIC-EXTERNAL 
relationship. For example, module A imports from module B a public variable that 
contains the address of a local or public procedure in B. Module A then performs a 
computed call to the procedure in B. The rule can be stated as follows: The linker 
assumes a connection from module A to module B if there exists an external refer- 
ence in A to a public procedure in B. In all other cases, hidden connections must be 
explicitly given as arguments to the OVERLAY control. 

Following is an example of a computed call to an external procedure: 

MODI: DO; 

DECLARE I _Q__C LEAR WORD EXTERNAL; 

CALL l„0_.CLEAR; 
END MODI; 
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In another module, you have: 



M D 2 : 



DO ; 



DECLARE 1_0_C LEAR WORD PUBLIC; 



READER; 



PROCEDURE ; 



I_0_ERR0R : 



PROCEDURE ; 



END I_0_ERR0R; 



I _0 _S U C C E S S : 



PROCEDURE ; 



EHD I__Q_SUCCESS ; 



IF ERR_C0DE <> 

THEN 1_0_CLEAR • .l_O_ERR0R; 
ELSE I _0_C LEAR ■ . I D S U C C E S S ; 



END READER ; 
END MODS ; 

In the above procedure, MODI invokes a procedure defined in MOD2. To prevent 
the linker from overlaying on-chip RAM variables of MOD2 with on-chip RAM 
variables of MODI, the following form of the OVERLAY control must be used: 

OVERLAY (MODI > M0D2) 

Overlaying can be a good way of economizing on-chip RAM space; however, overlay- 
ing may, in some cases, give worse results. For example, if most procedures call one 
another, the resulting segments will expand, making it more difficult for the linker to 
allocate a few large segments than many small ones. 

The outcome of the overlaying process can be checked by inspecting the link map. 
All overlaid segments are indicated by "OVERLAP**. Warning (4), DATA SPACE 
MEMORY OVERLAP, is not generated for those segments. 



Most of the command words in the RL51 command have short forms to save you 
keystrokes over the full spellings. Here is a list of the command words and their 
abbreviations. 



Abbreviations for Command Words 



Command Word 



Abbreviation 



BIT 

CODE 

DATA 

DEBUGLINES 

DEBUGPUBLICS 

DEBUGS YMBOLS 

GENERATED 

IDATA 

IXREF 

LIBRARIES 



Bl 

CO 

DT 

DL 

DP 

DS 

GN 

ID 

IX 

LB 



Using the RL51 Program 3-15 



LINES LI 

MAP MA 

NAME NA 

NODEBUGLINES NODL 

NODEBUGPUBLICS NODP 

NODEBUGSYMBOLS NODS 

NOGENERATED NOGN 

NOIXREF NOIX 

NOLIBRARIES NOLB 

NOLINES NOLI 

NOMAP NOMA 

NOOVERLAY NOOL 

NOPRINT NOPR 

NOPUBLICS NOPL 

NOSYMBOLS NOSB 

OVERLAY OL 

PAGEWIDTH PW 

PRECEDE PC 

PRINT PR 

PUBLICS PL 

RAMSIZE RS 
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The RL51 program produces three outputs: console displays, a listing file, and the 
absolute object module file. This chapter describes these outputs and gives examples. 
As discussed in Chapter 3, the listing controls in the RL51 command allow the user 
to suppress some information in the listing file, and the linking controls can suppress 
some information in the absolute object file. 



Console Display 

The console displays produced by RL51 consist of a sign-on message and any error 
messages that occur. The sign-on is as follows: 

system-id MCS-51 RELOCATDR AND LINKER Vx.y 
where 

x.y is the version number. 



Listing File 

RL51 produces a listing file unless it is suppressed in the RL5 1 invocation. The RL5 1 
listing file contains: 

• A summary of the link and locate process 

• A symbol table, as specified in the RL5I invocation 

• An inter-module cross-reference listing (IXREF) 

• Error messages detected by RL5I 



Link Summary 

A sample of a link summary is shown in figure 4- 1 . The summary includes the follow- 
ing kinds of information: 

• A header echoing the RL51 invocation. 

• Input modules included in the link process. Input modules are identified by module 
name and file name. 

• A link map (unless suppressed by the NOMAP control). The map lists all 
allocated segments, giving the type, base address, and length of each segment. 
The map also identifies segment overlaps and gaps in the memory space. 

• A list of segments that were ignored in the link process. If any segments were 
ignored, the reasons for doing so will be reported later as an error. 

• A list of unresolved external symbols. An external symbol is unresolved when it 
is not matched by a public symbol in one of the input modules. Each occurrence 
of an unresolved external symbol in a module will be reported later as an error. 

• A list of all symbols );hat were ignored in the locate process. A symbol is ignored 
when the same name appears as a public symbol in different modules, or has 
attributes that are incompatible with external references, or belongs to an ignored 
segment. Each occurrence of an ignored symbol in a module will be reported 
later as an error. 



* 
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system-id MCS-51 RELOCATOR AND 
RL51 F I L E 1 . E X T ( MOD 1 , M0D2 ) , 
NAME (EXAMPLE) MAP PRINT (: 


LINKER, Vx.y 
F I L E 2 . E X T TO 
LP:) 


INVOKED BY : 
OUTFIL .EXT 


1 


I NPUT MODULES I HCLUDED 
F I L E 1 . E XT (MOD 1 > 
F I L E 1 . E X T (MOD2 ) 
F 1 LE2 . EX T( M0D3 ) 








LINK MAP FOR OUTFIL 


. E X T ( E X AMPL E ) 






TYPE 


BASE 


LENGTH 


RELOCATION 


SEGMENT NAME 


REG 

DATA 

DATA 

• 'OVERLAP ' • REG 
BIT 

DATA 
DATA 
I DATA 


H 
8 H 
H H 
1 8H 
2 H 
2 1 H . 6 
2 2H 
2 3 H 
2 E H 
7 H 


8 H 
00 1 OH 
8H 
8 H 
1 H . 6 
H . 2 
1 H 
OBH 
4 2 H 
00 1 OH 


UNIT 

ABSOLUTE 

UNIT 

B 1 TA DDR 
ABSOLUTE 
UNI T 


"REG BANK 0" 
DAT A_S E G_1 

"REG BANK 3" 
A_B 1 T_S E G 
• • * GAP • * * 

DATA_SEG_2 

STAC K_S E G 
•••GAP'** 


XDATA 


O0O0H 


C H 


UNIT 


DYNAM I C_MEM 


CODE 
CODE 


H 

1 38 9H 
1 80 OH 


1 3 89H 
4 7 7H 
07A5H 


UNIT 

1 NBLOCK 


PROC 1 
•••GAP*'* 

PR0C2 


IGNORED SEGMENTS 
DYNAMIC POOL 










UNRESOLVED EXTERNAL 
INVERT 


SYMBOLS 








I GNORED SYMBOL S 
Bl T2SG 











Figure 4-1. Link Summary 



NOTE 

1 . For bit addresses, the display format is byte-address.bit-address (example: 
0020H.7 for bit 7 or byte 0020H). However, when bit or a byte is 
rererenced, only the byte address is displayed (the .0 is not displayed). 

2. References to an unresolved external symbol, an external symbol refer- 
ring to an ignored public symbol, or a reference to an ignored segment 
will produce additional error messages. 



Symbol Table 

The listing Tile contains a symbol table as specified by the SYMBOLS, PUBLICS, 
and LINES controls in the RL5I invocation. A sample symbol table is shown in 
figure 4-2. 
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SYMBOL TABLE 


FOR OUTF I LE . E XT( E X AMPLE > 




VALUE 


TYPE 
.... 


NAME 
.... 




MODULE 


MEMR Y 


D : 3 2 H 


PUBLIC 


LOW_MEM_PTR 


B : 2 H 


PUBLIC 


I N I T__F LAG 


B : 2 H . 1 


PUBLIC 


FULL_FL AO 


D : 3 4 H 


PUBLIC 


H I G H_M E M_P T R 


X : OH 


PUBLIC 


DYNAMI C_M EMORY 




PRDC 


ALLOCATE 


D: 6 4 H 


SYMBOL 


H U M_B Y T E S 


: 66 H 


SYMBOL 


POOL_SELECTOR 


D : 068H 


SYMBOL 


A L L C_P T R 


B : 2 OH . 2 


SYMBOL 


FLAG 


C : OH 


LINE' 


1 9 


C : 7 H 


LINE' 


20 


C : 00 1 H 


L I HE' 


2 1 


C ; 1 3 H 


LINE' 


2 2 




00 




D : 6 A H 


SYMBOL 


I 


C : 00 1 SH 


LINE' 


23 


C : 2 1 H 


LINE' 


2 4 


C : 2 6H 


LINE' 


25 


C : 2 FH 


LINE' 


26 


C : 3 2 H 


LINE' 


2 7 




ENDDO 




C : 3 7 H 


LINE' 


2B 


C : 04 OH 


LINE' 


29 


C : 4 F K 


LINE' 


30 


C ; 5 7 H 


LINE' 


3 1 


C : 5 FH 


LINE' 


32 


C : 6 6H 


LINE' 


33 


C : 6 F K 


LINE' 


34 


C : 7 6 H 


L I HE ' 


35 


C : 00B2H 


LINE' 


36 


C : 08FH 


LINE' 


3 7 


C : 94 H 


LINE' 


36 




ENDPROC 


ALLOCATE 




E N DMOD 


MEMR Y 



Figure 4-2. Symbol Table 



NOTE 

The information in the listing file is taken from the input object modules. If 
these are generated without the DEBUG option, the SYMBOLS, PUBLICS, 
and LINES information will not be available for listing. 



The symbol table contains scope definitions and information about the symbols and 
line numbers. Scope definition identifies the module, DO block or procedure that 
contains the symbol or line number. Note that when the table contains only public 
symbols (i.e., NOSYMBOLS and NOLINES controls are in effect), scope definition 
is by module only. 
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Each entry in the table consists of three parts, as follows: 

• VALUE. The value is the absolute address of the symbol. The address is prefixed 
with a letter indicating the type of address space (C, code; D, internal data; I, 
indirect internal data; B, bit space; X, external data; N, typeless number). A byte 
address (or a bit address on a byte boundary) is shown as a four-digit hexadecimal 
number (example; 00E0H). A bit address (unless it is on a byte boundary) is 
shown as a byte address followed by a period and the bit offset (I through 7) 
into the byte. 

• TYPE. The type field identifies the entry as a local symbol (SYMBOL), a public 
symbol (PUBLIC), segment (SEGMENT), or a line number (LINE#). 

• NAME. The name field gives the name of the symbol, or the number of the line. 

For scope definition, a line is printed for the beginning and end of each block. The 
TYPE field shows the type of block (MODULE, DO, or PROC for PROCEDURE), 
and the end of each block (ENDMOD, ENDDO, ENDPROC). The NAME field 
shows the name of the block, if any. 



NOTE 

Line number information and scope definitions other than MODULE are 
applicable only to object files produced by high-level language translators 
(e.g., PL/M-51). 



Inter-Module Cross-Reference Report (IXREF) 

The listing file contains an IXREF report as specified by the IXREF control and its 
associated selection list in the RL51 invocation. A sample IXREF report is shown in 
figure 4-3. 

The IXREF report consists of an alphabetically sorted list of symbols. Each such 
symbol begins a new line and represents a symbol that was declared as PUBLIC or 
EXTERNAL in at least one of the input modules. Each symbol is followed by its 
corresponding address space, followed by a semicolon. To the right of the semicolon 
starts a list of modules in which the symbol was declared PUBLIC or EXTERNAL. 
The first module name in the list is the one in which the symbol was declared PUBLIC. 
If a symbol is unresolved, or if a symbol is defined in a library and the NOLIBRAR- 
IES selection item is in effect, then the string ** UNRESOLVED *• appears in front 
of the modules list. 



Error Messages 

RL5I displays error messages on the console and copies them to the end of the listing 
file unless the listing file is suppressed. 

RL51 error messages describe warnings, errors, and fatal errors. A warning is a 
detected condition that may or may not be what the user desired; a warning does not 
terminate the link/locate operation. An error does not terminate operation, but 
probably results in an output module that cannot be used. A fatal error terminates 
operation of RL51. 

Refer to Appendix B for a list of the error messages and probable causes. 
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INTER -MODULE CROSS- 


REFERENCE LISTING 








NAME. 


USAGE MODULE 


NAMES 


? C H E C K_E ? B ¥ T E . . . 


DATA 


C H K E Q 


TESBAS 








?CHECK_EQ_BIT5?BIT . 


BIT; 


C H K E Q 










P 8 


CODE 


? P 8 


TESBAS 










CODE 


? P 1 S 


TESBAS 








? P T 6 


CODE 


? P 1 6 


TESBAS 










CODE 


TESB AS 


? P I V R 










CODE 


? P IVOR 


TESBAS 










NUMB 


TESBAS 


? P I V R 








CHECK.EQ 


CODE 


CHKEQ 


TESBAS 








CHE CK_EQ_B1 TS . . . 


CODE 


CHKEQ 










CHECK EXIT 


CODE 


CHKEQ 












CODE 


CHKEQ 












CODE 


M D U L E_ 


MODULE_l 


MODULE 


_2 






CODE 


M D U L E_ 


MODULE_1 


MODULE 


.2 




P U B 2 


CODE 


M D U L E_ 


MODULE.1 


MODULE 


.2 






CODE 


UNRESOLVED 


MODULE_1 


MODULE 


_2 




CODE 


MODULE. 


MODULE_1 


MODULE 


.2 






CODE 


M D U L E_ 


MQDULE_J 


MODULE 


_2 






CODE 


• * UNRESOLVED • * 


MODUL E_l 


MODULE 


_2 




CODE 


MODULE. 


MODULE_1 


MODULE 


.2 






CODE 


MODULE^ 


MODULE.1 


MODULE 


.2 






CODE 


MODULE. 


MODULE.1 


MODULE 


_2 






CODE 


MODULE. 











PUBU 


XDATA; M D U L E_ 











PUB12 


DATA 


MODULE. 











PUB 1 3 


IDATA; MODULE^ 











PUBU 


BIT; 


MODULE. 











PUB15 


NUMB 


MODULE. 











PUB16 


CODE 


MODULE. 













CODE 


MODULE. 











PUBIS 


CODE 


MODULE. 











PUB1 9 


CODE 


MODULE. 













CODE 


MO DUL E_ 


1 MODULE_0 










CODE 


MODULE. 


1 MODULE.O 










CODE 


* * UNRESOLVED * • 


MODULES 


MODULE 


.2 




CODE 


• • UNRESOLVED • • 


MODULE_1 







Figure 4-3. IXREF Listing 



Absolute Object File 

The linking and locating process combines one or more relocatable object files into 
one absolute object file. The absolute object file contains one module; the absolute 
module consists of 

• A module header record that identifies the module. 

• A set of intermixed content and debug records. The content records contain the 
program code. The debug records contain the location and scope of local symbols, 
public symbols, segment symbols, and line numbers, as specified by the DEBUG- 
SYMBOLS, DEBUGPUBLICS, and DEBUG LINES controls in the RL5I 
invocation. 

• A module end record that verifies the module name. 



Examples of Program Development 



This chapter shows three brief examples of program development using ASM51, 
PL/M-51, and RL51. The first example is the sample program discussed in the 
ASM5I User's Guide; the example shows how to assemble each of the three modules, 
then link and locate them into a single absolute object module with RL51. The second 
example is a short program that illustrates the use of the locating controls. The third 
example shows the use of RL5I with PL/M-51 modules, emphasizing the library 
process. 



Using Multiple Modules 

The first example is a program of three modules, named SAMPLE, CONSOLE_IO, 
and NUM_CONVERSION. The source for these modules is in three files, 
SAMP1.A51, SAMP2.A5I, and SAMP3.A51, respectively. To assemble these 
modules, invoke the assembler as follows: 

ASM 51 SAMP1.AS1 DEBUG 

ASMS1 SAMP 2 . A 5 1 DEBUG 

ASM51 SAMP3.AS1 DEBUG 

Note that this example assumes the three source files are on the same directory or 
device as the assembler and linker/locator, and that the output file will be sent to the 
same directory or device. The assembler invocations use the DEBUG control to have 
the symbol tables output to the object files for the three modules. 

After assembly is complete, the system has created object files SAMP I. OBJ, 
SAMP2.0BJ, and SAMP3.0BJ, and listing files SAMP1.LST, SAMP2.LST and 
SAMP3.LST. The three listing files are shown in figures 5-1, 5-2, and 5-3. 

To link and locate the three modules, enter the command 

RL51 SAMP1.0BJ, SAMP2.0BJ, SAMPS. OBJ * 
•*T0 SAMPLE I 

"PRINT (SAMPLE. LST) SYMBOLS LINES PUBLICS 

After the RL51 program has executed, the system has placed the absolute object 
module in file SAMPLE, and an output file with information on the link and locate 
process in file SAMPLE. LST. The output file also contains symbol table information 
as requested by the SYMBOLS, LINES, and PUBLICS controls. The listing file is 
shown in figures 5-1 through 5-3; figure 5-4 shows the output file. 
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Using the Locating Controls 

The second example shows how to use the PRECEDE control to specify an order for 
data segments, in this case because the RL51 algorithm for locating segments results 
in a segment being left out. 

The program is named TEST01. After assembly, the listing of TEST01.OBJ is as 
shown in figure 5-5. The program's code sequence is irrelevant to the example. The 
two DATA segments, SEGl and SEG2, and the BIT segment, BIT3, are the points 
of interest for this example. 

SEGl is 21 H byte:; long; SEG2, 50H bytes long; SEG3, one bit long. The assembler 
listing also shows working register bank (8 bytes long, absolutely located at addresses 
00H through 07H). 

All these segments are to be located in the on-chip data RAM of an 8051. For the 
8051, the directly-addressable on-chip data RAM is 80H bytes long (addresses 00H 
through 7FH); addresses 20H through 2FH are bit-addressable. The working regis- 
ters may occupy the first 20H bytes of the space. To see what RL51 does with this 
program, enter the command 



R C 5 1 TEST01.OBJ 



The RL51 listing file is shown in figure 5-6. ERROR 107 informs us that the locate 
attempt for SEGl would overflow the data space; SEGl was ignored (not located) 
for this reason. The link map shows the following assignments for the remaining 
segments: 



Addresses Segment 

00H - 07 H Register Bank 

08H-1FH GAP 

20H SEG3 (one bit at bit location 0) 

20H.1 - 20H.7 GAP 

21H-71H SEG2 (50H bytes) 



After these segments have been located, there is not enough room for SEGl (21H 
bytes). However, there would be enough room if SEGl were located before the BIT 
segment. To obtain this result, the command is 



RLS1 TEST01.0BJ PRECEDE(SEGI) 



The RL51 listing file for this example is shown in Figure 5-7. The PRECEDE control 
caused the link mapping to be as follows: 



Addresses Segment 

00H - 07H Register Bank 

08H-28H SEGl (21 H bytes) 

29H SEG3 (one bit at bit location 0) 

29H.1-29H.7 GAP 

2AH - 7AH SEG2 (50H bytes) 



Refer to Chapter 2 for details on RL51's allocating algorithm. 



Using RL51 with PL/M-51 Modules 

The third example shows how to use RL51 with object modules produced by 
PL/M-51. The example shows the use of PLM5I.LIB and demonstrates PL/M-51 
generated segments and the PL/M-51 to ASM51 linkage. 
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The entire application introduces a way to halt ICE-51 the 8051 In-Circuit Emulator 
Program, at run time. The procedure CHECK_EQUAL in the PL/M-5I module 
CHK_EQ checks if an arithmetic expression is true. If yes, it calls the HALT_ICE 
assembler routine, which causes ICE51 to stop the program that is currently running. 
The code of the program is irrelevant; the example merely intends to show the program 
development process. 

The PLM51 main module CHK_EQ is compiled by 
PLMS1 CHKEQ.PS1 DEBUG PWOO) 
The output of the compilation is shown in figure 5-8. 
The ASM51 module HLTICE is assembled by 
ASM51 HLTICE. A51 DEBUG PWOO) 
The output of the compilation is shown in figure 5-9. 
RL51 is invoked by the following command: 

RLS1 CHKEQ. OBJ, HLTICE. OBJ, PLM51. LIB r X R E F PW(72) 

RL5! links the two pre-translated input modules, along with the mandatory library 
PLM51.LIB. PLM51.LIB must be linked whenever a PL/M-51 module participates 
in the linkage. The listing files are shown in figures 5-8 and 5-9. The result of the 
linkage is shown in figure 5-10. 

The result of a linkage process that includes PL/M-51 modules deserves an expla- 
nation. The following paragraphs describe the modules, segments, and symbols that 
appear in the output listing of such a linkage. The explanation refers to the actual 
example (figure 5-10). 

In addition to the two input modules CHK_EQ and HALT_ICE, RL51 pulled some 
modules from PLM51.LIB. The two modules 7P0034 and 7P0038 contain common 
PL/M-51 run-time routines and were pulled to resolve calls to those routines in the 
CHK_EQ module. The module 7PIV0R contains the initialization routine (set the 
stack pointer, set PSW), and is pulled whenever a linkage process encounters a main 
module written in PL/M-51. 

The segments BYTES, BITS, and PROG are the user segments as defined in the 
ASM51 HALT_ICE module. The code segments 7P0034S, 7P0038S and 7PIV0RS 
are the code segments of the previously explained run-time routines. 

All segments whose names are of the form ?CHK_EQ?any are segments generated 
by PL/M-51 as result of compiling module CHK_EQ. The prefix ?CHK_EQ7 
indicates that the segment belongs to the CHK_EQ module. The suffix indicates the 
segment type; e.g, PR stands for the PRogram CODE segment, CO for the COnstant 
CODE segment, DT for DATA segment, and BI for BIT segment. 

On-chip segment names may be followed by a register bank number (0-3). This 
number indicates the register bank that must be in effect while data in this segment 
is accessed. 

The 7STACK segment was discussed before. Note that this segment is not supplied 
by the user, but is pulled.-automatically from PLM51.LIB because the main module 
is written in PL/M-51. The absolute segment at OOOOH-0002H contains the reset 
vector, which consists of a JUMP to the initialization routine contained in the 
7PIV0RS segment. 
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Most of PL/M-51 -generated relocatable segments have the UNIT relocation type. A 
frequent exception is the program code segment (?CHK_EQ?PR), which is 
INBLOCK whenever a module is compiled under ROM (MEDIUM), which is the 
default used by the compiler. Another (less frequent) exception is the BITADDRESS- 
ABLE DATA segment generated when bit structures are declared within the PL/M-5 1 
source program. 

User symbols appear in the symbol table and the IXREF report. Symbols whose 
names are equal to segments and modules defined previously represent entry points in 
the appropriate modules/segments pulled from PLM5 1 .LIB (e.g. , the symbol 7P0034 
is a code address in the module 7P0034). 

Symbols in the format ?procedure?BYTE or ?procedure?Qn (e.g., 
?HALT_ICE?BYTE) are DATA and BIT addresses used for passing parameters to the 
appropriate external procedures (as implied by the name). BYTE and WORD 
parameters are placed at DATA address starting at, for example, 
? H A LT_ICE? BY TE . BIT parameters are ptaced at BIT address starting at 
?HALT_ICE?BIT (see also the PL/M-51 User's Guide about PL/M-51 linkage to 
ASM51). 
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LIB51 Librarian 



Introduction 

LIB51 allows you to create, modify, and examine library files. It may be executed in 
interactive or noninteractive mode. In both cases, L1B51 can be invoked directly or 
by a submit file. 



Invoking LIB51 
Noninteractive Mode 

Following is the general syntax for invoking in non-interactive mode: 
t directory \ device ] L I B 5 1 command 

The librarian will then respond with the sign-on message. It then executes the given 
command and returns immediately to the host operating system. 



Interactive Mode 

Following is the general syntax for invoking L1B51 in interactive mode: 
t directory I device 1 L I B 5 1 

L1B5I will then respond with its sign-on message. It will then present the prompt (*), 
requesting that you enter L1B51 commands. After each command is executed, another 
prompt will appear as the librarian awaits entry of the next command. This process 
continues until the EXIT command is entered, thus terminating L1B5I. 



Character Set 

The L1B51 character set consists of the letters A-Z, the digits 0-9 and the special 
characters ?, @, and _. 



LIB51 Commands 

Table 6- 1 summarizes the LIB51 commands. 



Command Entry 

It is often necessary to extend the LIB command to more than one line. Use an 
ampersand (&) to indicate that you have not entered the complete command and are 
extending it to another line, The ampersand continuation character may be placed 
anywhere that a space would normally appear in the command line. That is, the 
continuation character may be placed before or after commas or parentheses and 
before or after control words. Any characters that appear on a line to the right of the 
ampersand and to the left of the carriage return terminating the line are ignored. 



Table 6-1. L1B51 Commands 



Command 


Abbreviation 


DstcrlptJon 


ADD i file[(modulel, ...])] > [,...] TO libraryjile 


A 


Adds modules to a 
library 


CREATE library file 


C 


Creates a library 
file 


DELETE library_file(module[, ...|) 


D 


Deletes modules 
from a library 


EXIT 


E 


Terminates 
session with LIB51 


EXTRACT i file[(module[....J)l > [.-J TO file 


X 


Extracts modules 
from libraries 


HELP 


H 


Displays syntax of 
LIB51 commands 


LIST < file[(module[,...])] } [,...] [TO file] [PUBLICS] 


L[P] 


Lists modules 
contained in librar- 
ies, and optionally 
lists all publics 


REPLACE { file[(module[,...[)] > |,...| IN libraryjile 


R 


Replaces modules 
in a library 



Whenever you enter the continuation character, L1B5I responds by beginning a new 
line with the continuation prompt — two asterisks (**). LIB51 then waits for you to 
enter the additional line of input. If you cannot complete the command on the second 
line, use more ampersands to continue the process until the command is completely 
entered. 

A semicolon may be placed on any command to start a comment. L1B5I will ignore 
all characters that appear to the right of the semicolon and to the left of the carriage 
return that terminates the line. If you enter an ampersand to the right of a semicolon, 
the ampersand will be treated as part of a comment and not as the continuation 
character. 
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Command Descriptions 

Following are the descriptions of the L1B5! commands. 

ADD 



Syntax 

ADD { f i 1 e [ ( modulel , . . . 1 ) ) } [,...] T D libraryjite 

Abbreviation 

A 



Description 

The ADD command allows you to add the specified files to the library file specified 
as the destination. 

The input filenames may be the names of ordinary object files or object library files. 
If the input file is an ordinary object file, all modules contained within that file will 
be added to the designated library. The ordinary object file may have been produced 
by a translator/assembler, RL5I, or the EXTRACT command of LIB51. 

If the input file is a library file, it may be specified with or without a list of module 
names, If you do not specify a list of module names, all of the modules contained in 
the input library will be added to the destination library. If you do specify the list of 
module names, only those modules specified in the command are added to the desti- 
nation library. 

The destination library must already exist before the ADD command is entered. 



Examples 



DD SIN .COiS , TflN TO USER.Ll 



This command adds the three files SIN, COS, and TAN to the destination library 
USER.LIB. 



DD LIB. TM|P (MODI, M0D2.MQD3) Tl 

P R J , T Mi 



This command adds the three modules MODI, MOD2, and MOD3 of the library 
LIB.TMP to the destination library PROJ.TOM. Note the use of the ampersand 
to continue the command. 
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CREATE 

Syntax 

CREATE library file 



Abbreviation 

C 



Description 

The CREATE command causes an empty library file that has been named in the 
command to be created. If the file already exists, an error message is issued and the 
command terminates. 



Examples 



CREATE SLE AZO .LIB 



This command creates the empty library file SLEAZO.LIB. 



LIB51 Librarian 6-5 



DELETE 



Syntax 

DELETE library file ( module name t , . . . J > 



Abbreviation 



D 



Description 

The DELETE command removes the specified modules from the designated library 
file. Modules can be deleted from only one library at a time. If any of the elements 
specified for deletion cannot be located, a warning is issued. 



Examples 



DELETE S L E.A Z Q . L i B ( T R U T H , V A L U E ) 



This command deletes the modules TRUTH and VALUE from the library 
SLEAZO.LIB. 



EXIT 



Syntax 

EXIT 

Abbreviation 

E 

Description 

In interactive mode, the EXIT command causes LIB51 to terminate — thereby causing 
control to be returned to the operating system. In noninteractive mode, the EXIT 
command is ignored. 



Examples 
i. '(HI 



■ EXIT 
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EXTRACT 

Syntax 

EXTRACT { filel C madulei ,..,))]> [,...] TO me 

Abbreviation 
X 



Description 

The EXTRACT command builds an ordinary object file from the specified files and 
library members. The extracted files are not deleted; they remain unchanged (i.e., 
they are nondestructively copied to their destination). 



Examples 



EXTRACT 5LEAZO.LIB(W0RTH,FREE) TO PRDLES.OBJ 



The modules WORTH and FREE are nondestructively extracted from 
SLEAZO.LIB and placed in PROLES.OBJ. 
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HELP 



Syntax 

HELP 



Abbreviation 

H 



Description 

The HELP command causes a summary of the syntax of the LIB51 command to 
appear on the console. Use the HELP command to obtain this information about 
LIB51 if you require help when entering commands. The following information will 
appear on the screen: 

ADD ifilel (.modulel ,...])]> [,...] TO tibraryjile 

CREATE library file 

DELETE library Jilei. module [,...)) 

EXIT 

EXTRACT { fitel i modulel ,...])]> t , . . , 1 TO file 
HELP 

LIST ifilel I modulel ,...])] } [,...] t TO file] [PUBLICS! 
REPLACE ifilel ( modulel , . . . J ) } > [,...] ! H libraryjile 
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LIST 



Syntax 

LIST ifilel {modulel ,...}) 1 ) [,...] I TO file) I PUBLICS] 



Abbreviation 

L [PI 



Description 

The LIST command prints the names of the modules, and, optionally, the names of 
the public symbols (if you specify PUBLICS) to the specified destination output file. 
If you do not enter the TO clause, the listing will be directed to the console output. 
PUBLICS specifies that in addition to the module names, all public symbols contained 
in those modules will be listed. 



Examples 



I. 



LIST U S Z R .'L I 3 



The names of all modules in the library USER. LIB are listed. 



USER.LIB(TEMP) PUBLICS 



All public symbols in the module TEMP in the library USER. LIB are listed. 
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REPLACE 

Syntax 

R E P L ft C E i filet I modulel , . . . J ) 1 ) [,...] IN libraryjile 



Abbreviation 



R 



Description 

The REPLACE command allows you to replace object modules in the designated 
library File with a new version. If a module designated to be replaced does not already 
exist in the library in an older version, the newer version is simply added to the library. 



Examples 



EPLflCE WORTH , FREE 1 N SLEAZO , L 



The newer version of WORTH is added to the library SLEAZO.LIB; the new 
file FREE is also added. 



Summary of RL51 Controls 



Table of Basic Definitions 

Table A-l gives definitions of basic terms used in the command format summary. 



Table A-l . Definitions of Common Terms 



Term 


Definition 


name 


Names can be from 1 to 40 characters long and must be composed 
ol letters A - Z, digits - 9, or special characters {?, @, _). The 
first character must be a letter or a special character. 


module-name 


Same as name. 


segment-name 


Same as name. 


pathname 


A valid filename relerence or device reference. See next two items 
for examples. 


filename 


A reference to a disk file. 


device 


A relerence to a non-disk device. 
Examples: :LP:, .CO:, :TO: 


value 


A 16-bit unsigned integer. 

Examples: 101 1 B, 304Q, 4096D (or just 4096), 0C300H 


address 


Same as value. 



RL51 Command Format Summary 

Here is a summary or the syntax of the RL5I invocation command. Refer to the 
Preface for an explanation of the command format notation. 

The RL51 command has the overall format 

[ directory \ device i R L 5 1 input-list [TO output-file) I control-list] 
where 

directory I device : • ; the directory or device where RL51 resides. 

input-list : • input-file I module-list I I , . . . ] 

input- file :• filename ; see table A-l 

module-list : • ( module-name [,...)) 

module-name :* ; see table A-l 

output-file :■ filename; see table A-l 

control-list ; ■ control . . . 
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control 



print i 

pathname 
pagewidth : • 
value : • 

map : 



symbols 
publics 
lines : 
ixret : 



listing-control 
linking-control 
locating-control 
configura t ion-con trol 
overlay-control 

I print 
pagewidth 
map 
symbols 
publics 
lines 
ixret 

PRINT t {pathname) ) I 
N P R INT 

■ ; see table A- 1 

• PAGEWIDTH ( value) 

see table A- 1 

MAP 
N M A P 

{ SYMBOLS 
| NOSYMBOL S 

PUBLICS 
NQPUBL I CS 

LINES \ 
N L I N E S ( 

1 X R E F t selection-list )\ 
NO I XREF I 

selection-list ; • ( selection-item [ 

generated 
libraries 



I ) 



selection-item 



generated 



■I 



GENERATED I 
NOGENERATED 



libraries 



I 1 BRAR I ES 
NOL I BRAR I ES 



linking-control : • 

debugsymbois 
debuglines •■ ■ 
debugpublics 

locating-controls : 



NAME ( module-name )\ 
debugsymbois I 
debuglines I 
debugpublics ) 

DE BUOSYMBOLS | 
NODEBUGSYMBOLSl 

DEBUGL I NES 
NQDEBUGL I NES 

DEBUGPUBL I CS 
NODEBUGPUBL 1 CS 



( segment I 




1 ) 



segment 



segment-name I I address) ] 
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segment-name :■ : see table A- 1 
address •■ • \ see table A- 1 

configuration-control : • ramsize 

ramsize RAMSIZE ( value ) 

value : * ! see table A-l 

overlay-control : - I J „ „ S r J ^ v u overlay-unit [ 1)1 



^ hTJQVERL A Y 
overlay-unit : • ov-module-name calls ov-module-name 

ov-module-name : • ! , . } 
[ module-name \ 

module-name : ■ ; see table A- 1 

calls : ■ > or 1 



Tables of Listing, Linking, Locating, and 
OverlayingControls 

Tables A-2 through A-6 describe the RL5I controls. Table A-7 gives abbreviations 
for the controls. 



Notes On Locating Controls 

The following notes refer to table A-4. 

1. Bit addresses for non-BIT segments in the BIT control must be on byte bounda- 
ries; that is, they must be divisible by eight, (BIT-type segments can be aligned 
on bit boundaries.) 

2. The range or addresses for the I DATA control is dependent on the target machine. 
The 8051 has 128 bytes (addresses 00H 7FH). See the RAMSIZE control in 
this context. 

3. The STACK control specifies which segments are to be allocated uppermost in 
the I DATA space. The memory accessed starts after the highest on-chip RAM 
address occupied by any previously allocated segment, and continues to the top 
of the I DATA space. 

NOTE 

This control has no other effect on any segments. 

The I DATA 7STACK segment, if it exists, is placed higher than segments 
that were mentioned in the STACK control. 



Table A-2 . Listing Controls and Switches 



Control 


Elfact 


PRINT [{pathname)] 


Sends the listing file to the tile or device specilied by 
pathname. 


NOPRINT 


Suppresses the listing file; overrides any of the following 
listing controls. 


PAGEWIDTH (value) 


Specifies the maximum page width to be used. 


MAP 


Outputs memory map to link summary. 


NOMAP 


Suppresses memory map. 


SYMBOLS 


Outputs local symbols to symbol table. 


NOSYMBOLS 


Suppresses local symbols. 



A-4 MCS®-51 



TaMe A-2 . Listing Controls and Switches (Cont'd . ) 



Control 


Effect 


NOPUBLICS 
LINES 

NOLINES 

IXREF [(selection-list )) 
NOIXHEF 


Outputs public symbols to symbol table 
Suppresses public symbols. 

Outputs line numbers to symbol table (high-level language 
translators only). 

Suppresses line numbers. 

Appends intermodule cross-reference report to print tile. 
Suppresses the intermodule cross-reference report. 



NOTE: The default for any control (except IXREF) is the positive form (PRINT, MAP, SYMBOLS, 
PUBLICS, and LINES). 



Table A-3. Linking Controls and Switches 



Control 


Effect 


NAME (module-name) 


Specifies the name of the output module. If the NAME control is 
omitted, the output module name defaults to the name of the first 
input module processed. 


DEBUGSYMBOLS 


Copies local symbol information to output file. 


NODEBUGSYMBOLS 


Suppresses local symbols. 


DEBUGPUBLICS 


Copies public symbol information to output file. 


NODEBUGPUBLICS 


Suppresses public symbols. 


DEBUGLINES 


Copies line number information (high-level language translators 
only) to output file. 


NODEBUGLINES 


Suppresses line numbers. 



NOTE: For all linking controls except NAME, the default is the positive form (DEBUGSYMBOLS, 
DEBUGPUBLICS, and DEBUGLINES). 

Table A-4. Locating Controls 



Control 


Address Space 


Address Range 
(Hex) 


Segment Types 
(and Attributes) 


PRECEDE 


Register banks and bit- 
addressable space in 
on-chip data RAM 


00H-2FH 


DATA (UNlT-aligned); 
IDATA 


BIT 


Bit-addressable space 
in on-chip data RAM 


00H - 7FH 
(see note 1) 


BIT; DATA; IDATA 


DATA 


Directly-addressable 
on-chip data RAM 


OOH - 7FH 


DATA (UNlT-aiigned); 
IDATA 


IDATA 


Indirectly-addressable 
on-chip data RAM 


OOH - OFFH 
(see note 2) 


IDATA 


STACK 


Same as IDATA (see 
note 3) 


Same as IDATA 


Same as IDATA 


XDATA 


External data RAM 


- OFFFFH 


XDATA 


CODE 


Code memory 


- OFFFFH 


CODE 



„ Table A-5. Configuration Control 



Control 


Effect 


RAMSIZE (value) 


Specifies the amount of on-chip RAM the object is aimed to. 
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Table A-6. Overlay Controls 



Control 


Effect 


OVERLAY (overlay-units) 
NOOVERLAY 


Overlays data segments, based on the information In the module 
declarations and in the overlay units. 

Suppresses the overlaying of data segments. 


Table A-7 . Abbreviations for Command Words 



Command Word 


Abbrovlatlon 


BIT 


Bl 


CODE 


CO 


DATA 


DT 


DEBUGLINES 


DL 


DEBUGPUBLICS 


DP 


DEBUGSYMBOLS 


DS 


GENERATED 


GN 


IDATA 


ID 


IXREF 


IX 


LIBRARIES 


LB 


LINES 


LI 


MAP 


MA 


NAME 


NA 


NfJUEoLKaLINbo 


NODL 


NUU tDUljrUtJLIL/o 


NODP 


NODEBUGSYMBOLS 


NODS 


NOGENERATED 


NOGN 


NOIXREF 


NOIX 


NOLIBRARIES 


NOLB 


NOLINES 


NOLI 


NOMAP 


NOMA 


NOOVERLAY 


NOOL 


NOPRINT 


NOPR 


NOPUBLICS 


NOPL 


NOSYMBOLS 


NOSB 


OVERLAY 


OL 


PAGEWIDTH 


PW 


PRECEDE 


PC 


PRINT 


PR 


PUBLICS 


PL 


RAMSIZE 


RS 


STACK 


ST 


SYMBOLS 


SB 


TO 


TO 


XDATA 


XD 



RL51 Error Messages 



RL5I error messages describe warnings, errors, and fatal errors. A warning is a 
detected condition that may or may not be what the user desired; a warning does not 
terminate the link/locate operation. An error does not terminate operation, but 
probably results in an output module that cannot be used. A fatal error terminates 
operation of RL5I. 

This appendix lists the warning, error, and fatal error messages in that order. The 
text of each message is in UPPER CASE. A brief explanation of the probable cause 
for the error condition accompanies each error message. 



Warnings 

WARNING f: UNRESOLVED EXTERNAL SYMBOL 
SYMBOL: external-name 
MODULE: file-name(module-name) 

The specified external symbol, requested in the specified module, has no matching 
public symbol in any of the input modules. 

WARNING 2: REFERENCE MADE TO UNRESOLVED EXTERNAL 
SYMBOL: external-name 
MODULE: file-name(module-name) 
REFERENCE: code-address 

The specified unresolved external is referenced in the specified module at the specified 
code address. 

WARNING 3: ASSIGNED ADDRESS NOT COMPATIBLE WITH 

A L I GNMENT 
SEGMENT: segment-name 

The address specified lor the segment in a locating control is not compatible with the 
segment's alignment. The segment is placed at the specified address, violating its 
alignment. 

WARNING 4: DATA SPACE MEMORY OVERLAP 
FROM: byte.bit address 

TO: byte.bit address 

The data space in the given range is occupied by two or more segments. 

WARNING S: CODE SPACE MEMORY OVERLAP 
FROM: byte address 

TO: byte address 

The code space in a given range is occupied by two or more segments. 

WARNING 6: XDATA SPACE MEMORY OVERLAP 
FROM: byte address 

TO: byte address 

The xdata space in the given range is occupied by two or more segments. 



WARNING 7: MODULE NAME NOT UNIQUE 
MODULE: flle-name(module-name) 



The specified name was used as the module name for more than one module. The 
specified module is not processed. 

WARNING 8: MODULE NAME EXPLICITLY REQUESTED FROM 

ANOTHER FILE 
MODULE: file-name(module-name) 

The specified module was requested, explicitly, to be processed from another file that 
has not yet been processed. The specified module is not processed. 

WARNING 9: EMPTY ABSOLUTE SEGMENT 
MODULE: file-name(module-name) 

The specified module contains an empty absolute segment. This segment is not 
allocated. The base address of this segment may be overlapped without any additional 
message. 



Errors 

ERROR 101: SEGMENT COMBINATION ERROR 
SEGMENT: segment-name 
MODULE: file-name(module-name) 

The attributes of the specified partial segment, in the specified module, contradict 
those of previous (unspecified) occurrences of partial segments with the same name. 
The segment is ignored. 

ERROR 10 3; EXTERNALS ATTRIBUTE MISMATCH 
SYMBOL: external-name 
MODULE: file-name(module-name) 

The attributes of the specified external symbol, in the specified module, contradict 
those of previous (unspecified) occurrences of public symbol with the same name, 
The specified symbol is ignored. 

ERROR 103: EXTERNAL ATTRIBUTES DO NOT MATCH PUBLIC 
SYMBOL: symbol-name 
MODULE: file-name(module-name) 

The attributes of the specified external (public) symbol, in the specified module, 
contradict those of previous (unspecified) occurrences of public (external) symbol 
with the same name. The specified symbol is ignored. 

ERROR 104: MULTIPLE PUBLIC DEFINITIONS 
SYMBOL: symbol-name 
MODULE: . file-name(modute-name) 

The specified public symbol, in the specified module, has already been defined in a 
previously (unspecified) processed module. The specified symbol is ignored. 
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ERROR 105: PUBLIC REFERS TO IGNORED SEGMENT 
SYMBOL: public-name 
SEGMENT: segment-name 

The specified public symbol is defined referencing the specified ignored segment. The 
specified public symbol is ignored. 

ERROR 106: SEGMENT OVERFLOW 
SEGMENT: segment-name 

The specified segment, after combination, is larger than the maximum segment size 
allowed for the segment according to its type or to the given locating control. The 
specified segment is ignored, 

ERROR 107: ADDRESS SPACE OVERFLOW 
SPACE: space-name 
SEGMENT: segment name 

RL51 was unable to allocate the specified relocatable segment, according to the 
segment relocation type, in the specified address space. The specified segment is 
ignored. 

ERROR 108: SEGMENT IN LOCATING CONTROL CANNOT BE 

ALLOCATED 
SEGMENT: segment name 

RL51 was unable to allocate the specified relocatable segment that appears in the 
locating control, according to the requirements imposed by the locating control and 
according to the segment relocation type. The specified segment is ignored. 

ERROR 109: EMPTY RELOCATABLE SEGMENT 
SEGMENT: segment-name 

The specified segment, after combination has zero size. The specified segment is 
ignored. 

ERROR 110: CANNOT FIND SEGMENT 
SEGMENT: segment-name 

The specified segment name occurred in the command tail but is not the name of any 
segment defined within the input files. The specified segment is ignored. 

ERROR 111: SPECIFIED BIT ADDRESS NOT OH BYTE BOUNDARY 
SEGMENT: segment-name 

The specified segment was requested in a BIT locating control. The segment is not a 
BIT segment, and the requested address is not on byte boundary. The specified 
segment is ignored. 

ERROR 112: SEGMENT TYPE NOT LEGAL FOR COMMAND 
SEGMENT: segment-name 

The specified segment is not one of the types that are legal for the locating control 
for which it is specified. The specified segment is ignored. 



ERROR 113: RESERVED . 
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ERROR 121: IMPROPER FIXUP 
MODULE: file-name(module-name) 
SEGMENT: segment-name 
OFFSET: pseg-offset 

An error occurred in the evaluation of a fixup. An example of this error is when the 
value of the fixup expression does not meet the requirements of the type of the 
referenced location. A fixup is an address that cannot be determined at compile/ 
assembly-time. It is marked as relocatable, and at RL-5) time is assigned an address. 
A fixup is the address assigned to that relocatable symbol. 

FATAL ERROR 208: INVALID FILE NAME 
partial command 

The file-name specified in the command is not a valid file name. The command is 
repeated up to and including the point or error. 



FATAL ERROR 209: FILE USED IH CONFLICTING CONTEXTS 
FILE: file-name 

The specified file is used in more than one context, for example, using the same file 
for both input and output. (This may be caused by specifying for the first input file 
a file that has no extension, and not specifying an output file.) 

FATAL ERROR 210: 1/0 ERROR, INPUT FILE; 
U D I ERROR: EXCEPTION <num> : <ext> 

FILE: file-name 

An I/O error was detected in accessing an input file. The text of the message includes 
a description of the specific I/O error that occurred. See the user's guide for your 
operating system for a list of possible I/O errors. 

FATAL ERROR 211: I/O ERROR, OUTPUT FILE; ERROR' 
FILE: file-name 

An I/O error was detected in accessing the output file. The text of the message 
includes a description of the specific I/O error that occurred. See the user's guide for 
your operating system for a list of possible I/O errors. 

FATAL ERROR 212: I/O ERROR, LISTING FILE; ERROR' 
FILE: file-name 

An I/O error was detected in accessing the listing file. The text of the message includes 
a description of the specific I/O error that occurred. See the user's guide for your 
operating system for a list of possible I/O errors. 

FATAL ERROR 213: 1/0 ERROR, TEMPORARY FILE; ERROR' 
FILE: file-name 

An I/O error was detected in accessing a temporary file. The text of the message 
includes a description of the specific I/O error that occurred. See the user's guide for 
your operating system for a list of possible I/O errors. 

FATAL ERROR 214; INPUT PHASE ERROR 
MODULE: file-name(module-name) 
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This error occurs when RL51 encounters different data during pass two than it read 
during pass one. 

FATAL ERROR 215: CHECK SUM ERRDR 
MODULE: file-name(modute-name) 

A bad check sum was detected in the input module. This indicates a bad input module 
or a read error. 

FATAL ERROR 216: INSUFFICIENT MEMORY 

The memory available for execution of RL51 has been used up. This is usually caused 
by too many external /public symbols or segments in the input files or by too many 
errors. 

FATAL ERROR 217: HO MODULE TO BE PROCESSED 

After scanning all the input files, no module was selected to be processed. This is 
usually caused by an empty input file(s) or incorrect module names in the input list. 

FATAL ERROR 218: NOT AN OBJECT FILE 
FILE: tile-name 

The file named in the message, judging by its first byte of data, is not a valid object 
file. 

FATAL ERROR 219: NOT AN 8051 OBJECT FILE 
FILE: file-name 

The translator-ID field in the module header record indicates that the specified module 
is not an 805 1 object module. 

FATAL ERROR 2 2 0: INVALID INPUT MODULE 
MODULE: file-name(module-name) 

The specified input module was found to be invalid. Possible causes are incorrect 
record order, incorrect record type, illegal field, illegal relation between fields, or a 
missing required record. This error could be the result of a translator record. 



FATAL ERROR 221: MODULE SPECIFIED MDRE THAN ONCE 
partial command 

The input list in the invocation line contains the same module name more than once. 
The command is repeated up to and including the point of error. 

FATAL ERROR 222: SEGMENT SPECIFIED MORE THAN DNCE 
partial command 

The locating controls in the invocation line contain the same segment name more 
than once. The command is repeated up to and including the point of error. 

FATAL ERROR 224: DUPLICATE KEYWORD 
partial command 
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The same keyword appears in the command more lhan once. The command is repeated 
up to and including the point of error. 

FATAL ERROR 225: SEGMENT ADDRESSES ARE NOT IN 
ASCENDING ORDER 

partial command 

The addresses of the segments within one locating control are not in ascending order. 
The command is repeated up to and including the point of error. 

FATAL ERROR 226: SEGMENT ADDRESS INVALID FOR CONTROL 
partial command 

The address requested for a segment is not valid for the given locating control. The 
command is repeated up to and including the point of error, 

FATAL ERROR 227: PAGEWIDTH PARAMETER OUT OF RANGE 
partial command 

The PAGEWIDTH parameter given is out of the acceptable range. 

FATAL ERROR 228: RAMSIZE PARAMETER OUT OF RANGE 

partial command 

The RAMSIZE parameter given is out of acceptable range. 



FATAL ERROR 229: I/O ERROR, OVERLAY FILE; ERROR' 
FILE: file-name 

An I/O error was detected in accessing an overlay file. The text of the message 
includes a description of the specific I/O error that occurred. See the user's guide for 
your operating system for a list of possible I/O errors. (This error occurs only if 
IXREF was requested. Its occurrence does not invalidate the output object file.) 

FATAL ERROR 230: INCOMPATIBLE OVERLAY VERSION 
FILE: file -name 

The overlay file, although loaded successfully, has a version number that is not the 
one expected by RL5I. The possible cause is that the RL5I program and the loaded 
overlay are not of the same version. (This error occurs only if IXREF or OVERLAY 
was requested. If only IXREF was requested, the output object file is valid.) 

FATAL ERROR 231: TOO MANY IXREF ENTRIES 

The number of IXREF entries (entry is a pair consisting of modules and symbol 
reference) is too large to be processed. The IXREF listing step is not performed. The 
NOLIBRARIES and NOGENERATED controls may be used in order to decrease 
this number and overcome the error. (This error occurs only if IXREF was requested. 
Its occurrence does not invalidate the output object file.) 

FATAL ERROR 232: OVERLAY CONTROL CONFLICTS XREF 
SELECTOR I TEMS 

The overlay control should not appear with the IXREF selector items NOLIBRAR- 
IES or NOGENERATED. 

FATAL ERROR 233: ILLEGAL USE OF • IN OVERLAY 
CONTROL 
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The use of * > * or * J * with the OVERLAY control is illegal. 

FATAL ERROR 2*0: INTERNAL PROCESS ERROR 

RL51 has detected thai it has made a processing error. This error indicates a bug 
within RL51. 



LIB51 Command Summary 




Table C-l . LIB51 Commands 



Command 


Abbreviation 


Description 


ADD { file[(module[, .|)] } [,.,.] TO libraryjile 


A 


Adds modules to a 
library 


CREATE library file 


C 


Creates a library 
(ile 


DELETE library_file{module|,...]) 


D 


Deletes modules 
from a library 


EXIT 


E 


Terminates 
session with 
LIB51 


EXTRACT { file[(module(, ...])] } [,...] TO file 


X 


Extracts modules 
from libraries 


HELP 


H 


Displays syntax of 
LIB96 commands 


LIST < (ile((module[,...])l > [....] (TO file] |PUBLICS| 


L[P) 


Lists modules 
contained in librar- 
ies, and optionally 
lists all publics 


REPLACE ffile|(module[....))|> |,...J IN libraryjile 


R 


Replaces modules 
in a library 



LIB51 Error Messages 




INSUFFICIENT MEMORY 

LIBS I cannot execute the command because it requires more memory than the amount 
of memory available in the system. 

I NVAL ID SYNTAX 

The command was not entered properly. Reenter it using the correct syntax. 
UNRECOGN I ZED COMMAND 

An illegal or misspelled command was entered. The only commands are ADD, 
CREATE, DELETE, EXIT, EXTRACT, HELP, LIST, REPLACE, and their 
respective abbreviations. 

INVALID MODULE NAME 

The specified module name contains an invalid character or starts with a digit. 

MODULE NAME TOO LONG 

The specified module name exceeds 40 characters. 

RIGHT PARENTHESIS EXPECTED 

A ")" is missing in the command. 

pathname , CHECKSUM ERROR 

The specified file has an error in one of its checksum fields. This is usually the result 
of an I/O error. 

pathname , ILLEGAL RECORD FORMAT 

This error is usually caused by an I/O error or a translation error. 

pathname, BAD RECORD SEQUENCE 

This error is usually caused by an I/O error or a translation error. 

pathname , DUPLICATE SYMBOL IN INPUT 

You have attempted to ADD or REPLACE a module that contains a public symbol 
that is already within the library. 

pathname , ATTEMPT TD ADD DUPLICATE MODULE 
The specified module name already appears within the library. 
pathname , FILE ALREADY EXISTS 

The specified file in the CREATE command already exists. Choose another name 
for the library. 



* • 



pathname , HOT LIBRARY 

The specified file is not a library. 

The TO filename is omitted in the ADD command. 

UNRECOGNIZED COMMAND 

An illegal or misspelled command was entered. The only legal commands are ADD, 
CREATE, DELETE. LIST, and EXIT. 

File or Module Errors 

The following errors indicate that there is some problem with the file or module 
specified. There is no partial copy of the command given with these error messages. 

FILE ALREADY EXISTS 

The file specified in the CREATE command already exists. Choose a new name for 
the library, 

filename , DUPLICATE SYMBOL IN INPUT 

You have attempted to add a file that contains a PUBLIC symbol already within the 
library. 

filename , NOT LIBRARY 
The specified file is not a library. 
filename ( modname) : NOT FOUND 

You have attempted to delete a module that does not exist. Check for misspelling of 
the filename or module name. 

modname— ATTEMPT TO ADD DUPLICATE MODULE 
The specified module name already appears within the library. 
symbol— ALREADY IN LIBRARY 

You have attempted to add a module that contains a PUBLIC symbol that is already 
in the library. 

filename, CHECKSUM ERROR 

filename, OBJECT RCCORD TOO SHORT 

filename, ILLEGAL RECORD FORMAT 

LIB51 cannot process the specified file because it is not a legal object file. Possible 
cause is a file damage or translator error. 



Hexadecimal-Decimal Conversion Table 



Table E-l is for hexadecimal to decimal and decimal to hexadecimal conversion. To 
find the decimal equivalent of a hexadecimal number, locate the hexadecimal number 
in the correct position and note the decimal equivalent. Add the decimal numbers. 

To find the hexadecimal equivalent of a decimal number, locate the next lower decimal 
number in the table and note the hexadecimal number and its position. Subtract the 
decimal number shown in the table from the starting number. Find the difference in 
the table. Continue this process until there is no difference. 



Table E-l . Hexadecimal-Decimal Conversion Table 



Moat Significant Byta 


Laatt Significant Byta 


Digit 4 


Digit 3 


Digit 2 


Digit 1 


HEX 


DEC 


HEX 


DEC 


HEX 


DEC 


HEX 


DEC 


























1 


4 096 


1 


256 


1 


16 


1 


1 


2 


8 192 


2 


512 


2 


32 


2 


2 


3 


12 268 


3 


768 


3 


48 


3 


3 


4 


16 384 


4 


1 024 


4 


64 


4 


4 


5 


20 480 


5 


1 280 


5 


60 


5 


5 


6 


24 576 


6 


1 536 


6 


96 


6 


6 


7 


28 672 


7 


1 792 


7 


112 


7 


7 


8 


32 768 


8 


2 048 


6 


128 


8 


8 


9 


36 864 


9 


2 304 


9 


144 


9 


9 


A 


40 960 


A 


2 560 


A 


160 


A 


10 


B 


45 056 


B 


2 816 


B 


176 


B 


11 


C 


49 152 


C 


3 072 


C 


192 


C 


12 


D 


53 248 


D 


3 328 


D 


208 


D 


13 


E 


57 344 


E 


3 546 


E 


224 


E 


14 


F 


61 440 


F 


3 840 


F 


240 


F 


15 
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abbreviations, 3-14, A-5 
absolute object file, 4-5 
absolute object module, 1-2 
absolute segments, 2-2 
ADD, 6-2 
address, 3-2 
address spaces, 2-3, 2-4 
allocation, 3-8 
allocation process, 2-3 
assembler (ASMS I), 1-3, 5-1 

BIT, 2-2, 2-3, 2-4, 3-9 
BITADDRESSABLE, 2-2, 2-3 
BLOCK, 2-2 

CODE, 2-2, 2-3, 3-9 
command entry, 3-1 
command, invocation, 

see invocation command 
comments, 3-2 
configuration controls, 3-1 1 
console display, 4-1 
continuation lines, 3-2 
control-list, 3-1 
controls, 3-4 

see also linking controls, listing controls, 

locating controls 
CREATE, 6-4 

DATA, 2-2, 2-3, 3-9 
DEBUG control, 1-3, 3-4 
debugging, 1-1 
DEBUGLINES, 3-7 
DEBUGPUBLICS, 3-7 
DEBUGSYMBOLS, 3-7 
DELETE, 6-5 

development process, 1-1, 1-2 
device, 3-2 

editor, text, 1-3 

error messages, 4-4, B-l, D-l 

EXIT, 6-6 

external references, 2-4 
filename, 3-2 

hexadecimal-decimal conversion, E-l 

ICE-51 in-circuit emulator, 1-3 
I DATA, 2-2, 2-3, 3-9 
in-circuit emulator, 

see ICE-51 in-circuit emulator 
INPAGE, 2-2 
input-list, 3-1, 3-2 
invocation command, 3-2, 6-1 

address, 3-2 

control-list, 3-1 

device, 3-2 

filename, 3-2 



input-list, 3-1, 3-2 
module-name, 3-2 
name, 3-2 
output-file, 3-3 
pathname, 3-2 
segment-name, 3-2 
IXREF, 4-4, 4-5 

L1B51, 6-1 
error messages, D-l, D-2 

LINES, 3-5, 3-6, 3-15 

linking controls, 3-8, A-3 
NAME, 3-7 

linking switches, 3-7 

DEBUGLINES, 3-7, 3-8 
DEBUGPUBLICS, 3-7, 3-8 
DEBUGSYMBOLS, 3-7, 3-8 
NODEBUGLINES, 3-8 
NODEBUG PUBLICS, 3-8 
NODEBUGSYMBOLS, 3-8 

link summary, 4-1 

LIST, 6-9 

listing controls, 3-4, A-3 

DEBUG control, 3-7 

listing file, 3-4 
listing file, 4-1 
listing switches, 3-6 

IXREF, 4-4, 4-5 

LINES, 3-5, 3-6 

MAP, 3-5, 3-6 

NOLINES, 3-6 

NOMAP, 3-6 

NOPUBLICS, 3-6 

NOSYMBOLS, 3-6 

PUBLICS, 3-5, 3-6 

SYMBOLS, 3-5, 3-6 
locating controls, 3-8, 3-9, 5-16, A-4 

BIT, 3-9 

CODE, 3-9 

DATA, 3-9 

I DATA, 3-9 

PRECEDE, 3-9, 5-16 

STACK, 3-9 

XDATA. 3-9 

major functions, 2-1 
MAP, 3-5, 3-6 
memory map, 3-4 
modifying, 1-1 
module, 1-2, 2-1 
modular programming, 1-1 
module-name, 3-2 

NAME, 3-7 
name, 3-2 

NODEBUGLINES, 3-8 
NODEBUGPUBLICS, 3-8 
NODEBUGSYMBOLS, 3-8 
NOIXREF, 3-6 
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NOL1NES, 3-6 
NOMAP, 3-6 
NOOVF.RLAY, 3-ll, 3-12 
NOPRINT, 3-5 
NOPUBLICS, 3-6 
NOSYMBOLS, 3-6 
notation. A- 1 

output-file, 3-3 
OVERLAY, 3-ll, 3-I2 

PAGE. 2-2, 2-3 
partial segments, 2-2 
pathname, 3-2 
PRECEDE, 3-9, 5-16 
PRINT, 3-4 
program, I -2 

program development, l-l, I-2 
PROM programmer, l-l 
PUBLICS, 3-5, 3-6 



RAMSIZE, 3-1 1 
relocatable segments, 2-2, 2-3 
relocation, 1-3, 2-2 
RL51, I-2, 2-I, 2-2, 3-I, 5-I 

command format. A- 1 
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